Prerequisites

  • Kubernetes cluster running Kubernetes v1.19.0 or greater
  • The osm-edge CLI or the helm 3 CLI or the OpenShift oc CLI.

Kubernetes support

osm-edge can be run on Kubernetes versions that are supported at the time of the osm-edge release. The current support matrix is:

osm-edge Kubernetes
1.1 1.19 - 1.24

Using the osm-edge CLI

Use the osm CLI to install the osm-edge control plane on to a Kubernetes cluster.

osm-edge CLI and Chart Compatibility

Each version of the osm-edge CLI is designed to work only with the matching version of the osm-edge Helm chart. Many operations may still work when some version skew exists, but those scenarios are not tested and issues that arise when using different CLI and chart versions may not get fixed even if reported.

Running the CLI

Run osm install to install the osm-edge control plane.

$ osm install
osm-edge installed successfully in namespace [osm-system] with mesh name [osm]

Run osm install --help for more options.

Note: Installing osm-edge via the CLI enforces deploying only one mesh in the cluster. osm-edge installs and manages the CRDs by adding a conversion webhook field to all the CRDs to support multiple API versions, which ties the CRDs to a specific instance of osm-edge. Hence, for osm-edge’s correct operation it is strongly recommended to have only one osm-edge mesh per cluster.

Using the Helm CLI

The osm-edge chart can be installed directly via the Helm CLI.

Editing the Values File

You can configure the osm-edge installation by overriding the values file.

  1. Create a copy of the values file (make sure to use the version for the chart you wish to install).

  2. Change any values you wish to customize. You can omit all other values.

    • To see which values correspond to the MeshConfig settings, see the osm-edge MeshConfig documentation

    • For example, to set the logLevel field in the MeshConfig to info, save the following as override.yaml:

      osm:
        sidecarLogLevel: info
      

Helm install

Then run the following helm install command. The chart version can be found in the Helm chart you wish to install here.

$ helm install <mesh name> osm --repo https://flomesh-io.github.io/osm-edge --version <chart version> --namespace <osm namespace> --values override.yaml

Omit the --values flag if you prefer to use the default settings.

Run helm install --help for more options.

OpenShift

To install osm-edge on OpenShift:

  1. Enable privileged init containers so that they can properly program iptables. The NET_ADMIN capability is not sufficient on OpenShift.
    osm install --set="osm.enablePrivilegedInitContainer=true"
    
    • If you have already installed osm-edge without enabling privileged init containers, set enablePrivilegedInitContainer to true in the osm-edge MeshConfig and restart any pods in the mesh.
  2. Add the privileged security context constraint to each service account in the mesh.
    • Install the oc CLI.
    • Add the security context constraint to the service account
       oc adm policy add-scc-to-user privileged -z <service account name> -n <service account namespace>
      

Pod Security Policy

Deprecated: PSP support has been deprecated in osm-edge since v0.10.0

PSP support will be removed in osm-edge 1.0.0

If you are running osm-edge in a cluster with PSPs enabled, pass in --set osm.pspEnabled=true to your osm install or helm install CLI command.

Enable Reconciler in osm-edge

If you wish to enable a reconciler in osm-edge, pass in --set osm.enableReconciler=true to your osm install or helm install CLI command. More information on the reconciler can be found in the Reconciler Guide.

Inspect osm-edge Components

A few components will be installed by default. Inspect them by using the following kubectl command:

# Replace osm-system with the namespace where osm-edge is installed
$ kubectl get pods,svc,secrets,meshconfigs,serviceaccount --namespace osm-system

A few cluster wide (non Namespaced components) will also be installed. Inspect them using the following kubectl command:

kubectl get clusterrolebinding,clusterrole,mutatingwebhookconfiguration,validatingwebhookconfigurations -l app.kubernetes.io/name=openservicemesh.io

Under the hood, osm is using Helm libraries to create a Helm release object in the control plane Namespace. The Helm release name is the mesh-name. The helm CLI can also be used to inspect Kubernetes manifests installed in more detail. Goto https://helm.sh for instructions to install Helm.

# Replace osm-system with the namespace where osm-edge is installed
$ helm get manifest osm --namespace osm-system

Next Steps

Now that the osm-edge control plane is up and running, add services to the mesh.