Installing the Instana Operator

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

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

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

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 each of the namespaces as follows:

# Create namespace in which secret is to be located
kubectl create ns instana-operator

# Create the secret
kubectl create secret docker-registry instana-registry \
    --namespace=instana-operator \
    --docker-username=_ \
    --docker-password=<agent_key> \
    --docker-server=artifact-public.instana.io

# Create the YAML for the secret without applying
kubectl create secret docker-registry instana-registry \
    --namespace=instana-operator \
    --docker-username=_ \
    --docker-password=<agent_key> \
    --docker-server=artifact-public.instana.io \
    --dry-run=client \
    --output=yaml

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.

The operator expects a secret instana-operator-webhook of type kubernetes.io/tls to be present.

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.

Refer to the cert-manager documentation for installation details.

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 the placeholders <namespace> and <clusterDomain> with values that apply for your setup.

# Create the secret
kubectl create secret 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
kubectl create secret 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

You can now proceed and install the operator. The plug-in provides the following two options.

Applying Manifests directly

This option creates CRDs, and installs the operator deployment and associated resources on the Kubernetes cluster. Note: 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.

# Install the operator in the current namespace
kubectl instana operator apply

# Install the operator in the specified namespace (e.g. instana-operator)
kubectl instana operator apply --namespace=instana-operator

# Install the operator in the current namespace by using custom certificates.
# In this case, the base64-encoded CA bundle needs to be specified
kubectl instana operator apply --ca-bundle-base64=<base64-encoded ca.crt file>

Rendering Manifests only

This option renders manifests to stdout or writes them to files in a specific directory.


# Write YAML files to the specified directory
kubectl instana operator template --output-dir <dir>

# Render YAML using a custom cluster domain
kubectl instana operator template --cluster-domain=my-domain.local

# Render YAML using custom certificates.
# In this case, the base64-encoded CA bundle needs to be specified
kubectl instana operator template --ca-bundle-base64=<base64-encoded ca.crt file>

You can now apply the manifests by using kubectl.

Advanced Operator configuration

The full set of configuration options for the operator is available by using a values file. The mechanism is the same as is used by Helm.

kubectl instana operator template --output-dir <dir> --values <path>

See the following example values file:

image:
  registry: my.registry.com

imagePullSecrets:
  - name: my-registry-secret

The available options are listed in the following table:

Key Type Default Description
fullnameOverride string "" Overrides the chart's fullname (instana-operator).
image.registry string "artifact-public.instana.io" The image registry to use.
image.repository string "infrastructure/instana-operator" The image repository to use.
image.tag string Automatically set by the kubectl plugin The image tag to use.
imagePullPolicy string "IfNotPresent" The image pull policy.
imagePullSecrets list [] A list of image pull secrets.
installCRDs bool true Specifies whether CRDs should be 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.hostNetwork bool false Use the host's network namespace. Enabling this also sets 'dnsPolicy' to 'ClusterFirstWithHostNet'.
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.hostNetwork bool false Use the host's network namespace. Enabling this also sets 'dnsPolicy' to 'ClusterFirstWithHostNet'.
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.