Installing the Instana Enterprise operator

This guide uses Kubernetes and Red Hat OpenShift interchangeably. The references of Kubernetes objects are also applicable to Red Hat OpenShift.

The Instana Enterprise operator must be installed with the help of the kubectl plug-in.

Before you can do so, you must configure a set of secrets.

Creating image pull secrets

Unless you have your own Docker registry that mirrors artifact-public.instana.io and don't require pull secrets, you need to create an image pull secret for the namespace where the Instana Enterprise operator will be installed. Follow the steps:

  1. Create a namespace where the Instana Enterprise operator will be installed.

    kubectl create ns <namespace_name>

    Replace <namespace_name> with the namespace name that you want, such as instana-operator.

  2. Install the secret in the namespace that you created by using either of the following ways:

    • Create the secret directly.

      kubectl create secret docker-registry <secret-name> \
    --namespace=<namespace_name> \
    --docker-username=_ \
    --docker-password=<agent_key> \
    --docker-server=artifact-public.instana.io
      • Replace <namespace_name> with the namespace name where the Instana Enterprise operator will be installed.
      • Replace <agent_key> with your agent key.
      • Replace <secret-name> with a secret name that you want.

    • Create the YAML for the secret without applying the YAML. The secret is printed without creation.

      kubectl create secret docker-registry <secret-name> \
    --namespace=<namespace_name> \
    --docker-username=_ \
    --docker-password=<agent_key> \
    --docker-server=artifact-public.instana.io \
    --dry-run=client \
    --output=yaml

      Then, create the secret.

      kubectl create -f <secret-file-name.yaml> --namespace <namespace>

Creating TLS secrets for admission webhook

The operator comes with an admission webhook for defaulting, validation, and version conversion. TLS is required for an admission webhook, that is, TLS certificates need to be in place.

Ensure that the TLS secret instana-operator-webhook of type kubernetes.io/tls is present. You can select to use either cert-manager or custom certificates.

Using cert-manager

By default, cert-manager is used to automatically provision the secret. This works out-of-the-box if cert-manager is installed on the cluster. In this case, Issuer and Certificate objects are created upon installation, which causes cert-manager to provision and inject the certificates.

For more information about cert-manager installation, see cert-manager documentation.

Using custom certificates

You are recommended to use cert-manager. However, if you prefer to provision the certificates yourself, you can do so. The secret must contain the following entries:

  • ca.crt
  • tls.crt
  • tls.key

The certificate (tls.crt) must contain the following DNS names:

  • instana-operator.<namespace>.svc
  • instana-operator.<namespace>.svc.<clusterDomain>
  • Replace <namespace> with the namespace name where the Instana Enterprise operator will be installed.
  • Replace <clusterDomain> with the domain name of the cluster where the Instana Enterprise operator will be installed.

To create a TLS secret instana-operator-webhook of type kubernetes.io/tls, use either of the following ways:

  • Create the secret directly.

    kubectl create secret generic instana-operator-webhook \
    --type=kubernetes.io/tls \
    --from-file=tls.key=path/to/tls.key \
    --from-file=tls.crt=path/to/tls.crt \
    --from-file=ca.crt=path/to/ca.crt

  • Create the YAML for the secret without applying. The secret is printed without creation.

    kubectl create secret generic instana-operator-webhook \
    --type=kubernetes.io/tls \
    --from-file=tls.key=path/to/tls.key \
    --from-file=tls.crt=path/to/tls.crt \
    --from-file=ca.crt=path/to/ca.crt \
    --dry-run=client \
    --output=yaml

    Then, create the secret.

    kubectl create -f <secret-file-name.yaml>

Creating the values file

The values file contains the configurations of the Instana Enterprise operator. The mechanism is the same as is used by Helm.

The available options that you can configure are listed in the Instana Enterprise operator configuration options table.

In addition to the default configurations in the values file, you need to update the imagePullSecrets field with the image pull secret that you created in the Creating image pull secrets section.

Create a values.yaml file in the working directory and add the following lines:

imagePullSecrets:
  - name: <image_pull_secret>

Replace <image_pull_secret> with the image pull secret that you created in the Creating image pull secrets section.

See the following example values file:

image:
  registry: my.registry.com

imagePullSecrets:
  - name: my-registry-secret

Installing the Instana Enterprise operator

You can now proceed to install the Instana Enterprise operator by using either of the following two options.

Applying manifests directly

This option creates CRDs and installs the Operator deployment and associated resources on the Kubernetes cluster.

Special care must be taken if you use cert-manager in combination with a custom cluster domain (that is, not cluster.local) or if you generated certificates yourself.

  • To install the Instana Enterprise operator in a specified namespace such as instana-operator, run the following command:

    kubectl instana operator apply --values values.yaml --namespace=instana-operator

  • To install the Instana Enterprise operator in a specified namespace by using custom certificates, run the following command:

    kubectl instana operator apply --values values.yaml --ca-bundle-base64=<base64-encoded ca.crt file> --namespace=instana-operator

    Replace <base64-encoded ca.crt file> with the base64-encoded CA bundle file name.

Rendering manifests first and applying manifests next

Render the manifests and write them to either standard output (STDOUT) or to files in a specific directory first. To render manifests, perform on of the following steps:

  • To render the YAML files with a specified namespace and write them to a specified directory:

    kubectl instana operator template --values values.yaml --namespace=instana-operator --output-dir <dir>

  • To render YAML files with a specified namespace and write them to a specified directory by using a custom cluster domain:

    kubectl instana operator template --values values.yaml --cluster-domain=my-domain.local --namespace=instana-operator --output-dir <dir>

  • To render YAML files with a specified namespace and write them to a specified directory by using custom certificates:

    kubectl instana operator template --values values.yaml --ca-bundle-base64=<base64-encoded ca.crt file> --namespace=instana-operator --output-dir <dir>

    Replace <base64-encoded ca.crt file> with the base64-encoded CA bundle file name.

Then, you can apply the manifests by using the commands in the Applying manifests directly.

Updating the backend version

The Instana backend is deployed with a default release version. Ideally, use the latest patch release or update to an available higher Instana backend version.

You can use the instana-kubectl versions commands to upgrade the Instana backend. For more information, see upgrade procedure.

Optional: Using advanced Operator configuration

After you install the Instana Enterprise operator, you can configure the Instana Enterprise operator by updating the values YAML file that you created in the Creating the values file section.

For the available options that you can configure, see the Instana Enterprise operator configuration options section.

After you update the values YAML file, apply the changes in a specified namespace as follows:

kubectl instana operator apply --values values.yaml --namespace=instana-operator

Instana Enterprise operator configuration options

The available options that you can configure are listed in the Instana Enterprise operator configuration options table.

Key Type Default Description
fullnameOverride string "" Overrides the chart's full name (instana-operator).
image.registry string "artifact-public.instana.io" The image registry to use.
image.repository string "infrastructure/instana-enterprise-operator" The image repository to use.
image.tag string Automatically set by the kubectl plug-in The image tag to use.
imagePullPolicy string "IfNotPresent" The image pull policy.
imagePullSecrets list [{"name":"instana-registry"}] A list of image pull secrets.
installCRDs bool true Specifies whether CRDs are installed.
nameOverride string "" Overrides the chart's name (instana-operator).
operator.affinity object {} Affinity for the operator pod.
operator.clusterDomain string "" Specifies a custom cluster domain.
operator.enabled bool true If true, the operator deployment is installed.
operator.extraArgs list [] Additional CLI arguments for the operator process.
operator.extraEnv list [] Additional environment variables for the operator process.
operator.nodeSelector object {} Node selector for the operator pod.
operator.replicas int 1 The number of replicas to create.
operator.resources object {} Resource requests and limits for the operator pod.
operator.securityContext object {"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true,"runAsNonRoot":true} Security context for the operator container.
operator.tolerations list [] Tolerations for the operator pod.
webhook.affinity object {} Affinity for the operator pod.
webhook.caBundleBase64 string "" Base64-encoded CA bundle for the webhook.
webhook.enabled bool true If true, the webhook deployment is installed.
webhook.extraArgs list [] Additional CLI arguments for the operator process.
webhook.extraEnv list [] Additional environment variables for the operator process.
webhook.nodeSelector object {} Node selector for the operator pod.
webhook.replicas int 1 The number of replicas to create.
webhook.resources object {} Resource requests and limits for the operator pod.
webhook.securityContext object {"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true,"runAsNonRoot":true} Security context for the operator container.
webhook.tolerations list [] Tolerations for the operator pod.

Checking Instana Enterprise operator status

To look for issues on the pods, check at the events on the pods.

To search for all the events, run one of the following commands:

   oc/kubectl get events -n instana-core

    oc/kubectl get events -n instana-units

If you see any errors, check the operator logs.

To check the operator logs, complete the following steps:

  1. Check the names and status of the operator:

        oc get pods -n instana-operator

  2. Check the logs of the operator

        oc logs -f -n instana-operator <Pod name>