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.

Creating image pull secrets
Creating TLS secrets for admission webhook
- Using cert-manager
- Using custom certificates
Creating and configuring the values file
Installing the Instana Operator
- Applying manifests directly
- Rendering manifests first and applying manifests next
Optional: Using advanced Operator configuration
- Instana Operator configuration options

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 Operator will be installed. Follow the steps:

Create a namespace where the Instana Operator will be installed.
```
kubectl create ns <namespace_name>
```
Replace <namespace_name> with the namespace name that you want, such as instana-operator.

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 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 Operator will be installed.
Replace <clusterDomain> with the domain name of the cluster where the Instana 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 and configuring the values file

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

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.

Generate a values file as follows:

kubectl instana operator template --output-dir /tmp --values values.yaml

Add the following lines to the values file:
```
imagePullSecrets:
- name: <image_pull_secret>
```
Note: 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
```

Apply the changes of the values file as follows:

kubectl instana operator apply --values /tmp/values.yaml

Installing the Instana Operator

You can now proceed to install the Instana 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.

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.

To install the Instana Operator in the current namespace, run the following command:
```
kubectl instana operator apply
```
To install the Instana Operator in a specified namespace such as instana-operator, run the following command:
```
kubectl instana operator apply --namespace=instana-operator
```
To install the Instana Operator in the current namespace by using custom certificates, run the following command:
```
kubectl instana operator apply --ca-bundle-base64=<base64-encoded ca.crt file>
```
Replace <base64-encoded ca.crt file> with the base64-encoded CA bundle file name.

Rendering manifests first and applying manifests next

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

To write YAML files to a specified directory, run the following command:
```
kubectl instana operator template --output-dir <dir>
```
To render YAML files by using a custom cluster domain, run the following command:
```
kubectl instana operator template --cluster-domain=my-domain.local
```
To render YAML files by using custom certificates, run the following command:
```
kubectl instana operator template --ca-bundle-base64=<base64-encoded ca.crt file>
```
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.

Optional: Using advanced Operator configuration

After you install the Instana Operator, you can configure the Instana Operator by updating the values YAML file that you created in the Creating and configuring the values file section.

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

After you update the values YAML file, apply the changes as follows:

kubectl instana operator apply --values /tmp/values.yaml

Instana Operator configuration options

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

Key	Type	Default value	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-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	`[]`	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	`[]`	Extra CLI arguments for the operator process.
operator.extraEnv	list	`[]`	Extra 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.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.