Installing the agent on Kubernetes
You can install the Instana agent in an online or offline (air-gapped) environment in a Kubernetes cluster. See the following list to check the prerequisite conditions, learn about all the available installation methods, and install the agent on Kubernetes.
Prerequisites
Before you install the host agent, ensure that the prerequisites are met.
Choosing how you want to install the agent
Choose one of the following installation options, and then click the associated link to continue:
-
In an offline (air-gapped) environment (where the host can communicate with the Instana hosted agent repositories), you must install the host agent either with the Kubernetes package manager Helm or with an operator. To continue, see Install by using Helm chart in an air-gapped environment and Install by using an operator in an air-gapped environment.
-
In an online environment, you can install the host agent by using one of the following methods:
-
To use all available configuration options, such as reporting to multiple backends, and have full control and even enable some options, you can install by using the Operator or install by using the Helm chart.
For all available configuration options for the Helm chart, see Configuration reference. These configuration options also apply to the Operator CRD in the same way.
-
If you want to install the agent quickly or if you do not need to apply further customization to your Instana agents and rely on manual
kubectl
handling, install the Instana agent using a static YAML within your Kubernetes cluster by customizing a YAML file. But you can't use the configuration options as the operator way or the Helm chart way.
-
Installing the agent in an air-gapped environment
You can install the agent in an air-gapped environment by using two methods:
Install by using Helm chart in an air-gapped environment
To install the agent in an air-gapped environment, complete the following steps:
In the following installation steps, the CentOS Linux distribution is used, but the steps are valid for all the other supported distributions.
-
Install Docker by running the following commands:
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl start docker
-
Install Helm by running the following commands:
sudo su
yum install -y epel-release
yum install -y snapd
systemctl enable --now snapd.socket
ln -s /var/lib/snapd/snap /snap
snap install helm --classic PATH="$PATH:/snap/bin/"
helm version
-
Install Minikube by completing the following steps:
These steps serve as an example to show the target environment.
-
Add the Kubernetes repository:
cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo [kubernetes] name=Kubernetes baseurl=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/ enabled=1 gpgcheck=1 gpgkey=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/repodata/repomd.xml.key exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni EOF
-
Install the kubectl command line tool:
sudo yum install -y kubectl
-
Download the Minikube RPM package:
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest.x86_64.rpm
-
Install the Minikube RPM package:
sudo rpm -Uvh minikube-latest.x86_64.rpm
-
Start a Kubernetes cluster by using Docker:
minikube start --force --driver=docker
-
Set up the Docker environment so that it can be used with Minikube:
eval $(minikube docker-env)
-
Check the Kubernetes cluster:
kubectl cluster-info
-
-
Pull the necessary Docker images for transfer to an air-gapped environment:
-
Log in to the Instana Container Registry with your agent key:
docker login https://containers.instana.io/v2 -u _ -p <agentKey>
-
Pull the latest version of the agent from the Instana Container Registry:
docker pull containers.instana.io/instana/release/agent/static:latest
-
Pull the latest version of the Instana Kubernetes sensor:
docker pull icr.io/instana/k8sensor:latest
-
Log out of the Docker registry:
docker logout
-
Convert the Docker images into
.tar
files:docker images
docker tag <instanaAgentImageID> instana/agent
docker save instana/agent > instana-agent.tar
docker tag <k8SensorID> instana/k8sensor
docker save instana/k8sensor > instana-k8sensor.tar
-
Copy files (
instana-agent.tar
andinstana-k8sensor.tar
) to the air-gapped host where you want to install the agent. -
Delete current images from the air-gapped host:
docker rmi -f <instanaAgentImageID> <k8SensorID>
-
Import images from
.tar
files (instana-agent.tar
andinstana-k8sensor.tar
):
docker load --input instana-agent.tar
docker load --input instana-k8sensor.tar
-
-
Run the Docker registry server and push images:
docker run -d -p 5000:5000 --restart=always --name registry registry:2
docker tag instana/agent:latest localhost:5000/instana-agent
docker push localhost:5000/instana-agent
docker tag instana/k8sensor:latest localhost:5000/instana-k8sensor
docker push localhost:5000/instana-k8sensor
#Delete all images related to the agent: docker rmi -f <instanaAgentImageID> <k8SensorID>
-
Pull Instana Helm charts from the following repository:
helm pull instana-agent --repo https://agents.instana.io/helm --untar instana-agent
Check for the latest Instana agent Helm chart file in your current directory.
-
Deploy the Instana agent into the Kubernetes cluster.
Instana agent Helm charts version 2.0.0 and earlier do not have the
instana-agent/crds
folder. Therefore, thekubectl apply -f instana-agent/crds
step is not required.kubectl apply -f instana-agent/crds && helm upgrade --install --create-namespace \ --namespace instana-agent \ --set agent.key=<agentKey> \ --set agent.endpointHost=ingress-red-saas.instana.io \ --set agent.endpointPort=443 \ --set cluster.name='mip-back-test' \ --set zone.name='mip-gke-zone' \ --set k8s_sensor.deployment.enabled=true \ --set k8s_sensor.image.name=localhost:5000/instana-k8sensor \ --set k8s_sensor.image.tag=latest \ --set k8s_sensor.image.pullPolicy=IfNotPresent \ --set agent.image.name=localhost:5000/instana-agent \ --set agent.image.tag=latest \ --set agent.image.pullPolicy=IfNotPresent \ instana-agent instana-agent/
Enter <agentKey>, and edit <agent.endpointHost>, <agent.endpointPort>, <k8_senosr.image.name>, and <agent.image.name>. Also, replace
instana-agent-1.2.61.tgz
with the latest Instana agent Helm chart file in your directory. -
Check your pods with the following command:
kubectl get all -n instana-agent
The agent is installed. For more information about the next steps, see the What to do next section.
Install by using an operator in an air-gapped environment
To install the agent in an air-gapped environment using an operator, complete the following steps:
-
Pull the following images.
docker pull containers.instana.io/instana/release/agent/static:latest docker pull icr.io/instana/k8sensor:latest docker pull icr.io/instana/instana-agent-operator:latest
-
Re-tag pulled images to a local image registry.
docker tag <public-image> <local-registry-image>
-
Push re-tagged images to the local image registry.
docker push <local-registry-image>
-
Create an image pull secret (Docker secret) in your target Kubernetes namespace:
kubectl create secret -n instana-agent docker-registry local-registry-image-pull-secret \ --docker-server=<your_local_image_registry> \ --docker-username= # Replace with ARTIFACTORY_USERNAME \ --docker-password= # Replace with ARTIFACTORY_PASSWORD
-
Fetch the YAML from GitHub:
curl -L -o instana-agent-operator.yaml https://github.com/instana/instana-agent-operator/releases/latest/download/instana-agent-operator.yaml
-
Replace image reference with the private registry. For example,
icr.io/instana/instana-agent-operator:2.1.8
with a private registry operator image. -
Apply the configuration to deploy the operator.
kubectl apply -f instana-agent-operator.yaml
-
If you do not have OpenShift CLI (
oc
) installed, you can download it from Getting started with the OpenShift CLI and patch the service account to have access to the image pull secret that you created in the previous section:oc patch serviceaccount instana-agent-operator -p '{"imagePullSecrets": [{"name": "local-registry-image-pull-secret"}]} -n instana-agent'
-
Create a file agent.yaml and update the agent custom resource to specific image versions:
apiVersion: instana.io/v1 kind: InstanaAgent metadata: name: instana-agent namespace: instana-agent spec: zone: name: # (optional) name of the zone of the host cluster: name: # cluster name. agent: image: name: # private registry static agent image. tag: # agent tag pullSecrets: - name: local-registry-image-pull-secret key: # fetch the download key from the Instana UI > Agents > Install Agent > Kubernetes Operator endpointHost: <your-ingress-endpoint> endpointPort: "443" env: {} configuration_yaml: | # You can leave this empty, or use this to configure your instana agent. # See https://docs.instana.io/setup_and_manage/host_agent/on/kubernetes/ k8s_sensor: image: name: # private registry k8 sensor image. tag: # k8 sensor tag
-
Deploy the custom resource:
$ kubectl apply -f agent.yaml
- Watch for all pods starting correctly.
The agent is installed. For more information about the next steps, see to the What to do next section.
Installing the agent in an online environment
You are recommended to use the following methods to install the Instana agent onto a Kubernetes cluster:
If you are reinstalling the agent, ensure that the agent has been cleanly uninstalled, including deleting all the agent's cluster level objects. For more information, see Uninstalling the Instana agent on Kubernetes.
New versions of the Operator, Helm chart, and YAML file are released fairly frequently. To keep up with the latest updates for fixes, improvements, and new features, ensure that you are running the current version of either Operator, Helm chart or YAML file.
To find the current version of the Operator, Helm chart, or YAML file, see the following topics:
Install by using the operator
You can use the Kubernetes operator that Instana provides to install the agent. Follow the steps:
-
Deploy the Operator as follows. The command installs the latest Operator.
kubectl apply -f https://github.com/instana/instana-agent-operator/releases/latest/download/instana-agent-operator.yaml
After you run this command, the operator is up and running in the namespace
instana-agent
, and waiting for aninstana-agent
custom resource to be created.The
latest
tag for the Instana agent Operator image in DockerHub and the Red Hat Registry is not supported.To get a new version of the Instana Agent Operator, update to the latest Operator YAML from the Operator's GitHub Releases page as mentioned previously.
-
On the home page of the Instana UI, click Deploy Agent.
-
On the agent deployment catalog page, click the tile Kubernetes - Operator.
-
Enter the cluster name and the agent zone (optionally) that you want the cluster to be part of.
The cluster name (
<your_cluster_name>
) is the customized name of the cluster that is monitored by this daemonset.The agent zone (
<your_zone_name>
) is used to customize the zone grouping, which is displayed on the infrastructure map. -
Create a custom resource YAML file by copying the YAML template provided in the Instana UI.
The YAML template is pre-filled with your agent key, host agent endpoint, cluster name, and agent zone.
-
Edit the custom resource YAML file:
-
The Instana agent custom resource supports the exact same configuration as the Instana Helm chart. For a detailed list of all the configuration parameters, see the Helm chart configurations.
-
If you want to install the agent in a self-hosted environment and the agent key does not have authority to download from the Instana public artifactory, add the download key as
downloadKey: <your_download_key>
. See the following example:agent: key: wPYpH7EGK0ucLaO0Nu7BYw downloadKey: m007YDoWNload6kE42yukg endpointHost: ...
-
If you want to add TLS encryption for the agent endpoint, use an existing secret or use a certificate and private key:
-
Use an existing secret
You can use an existing secret of the type
kubernetes.io/tls
for TLS encryption. But you must provideagent.tls.secretName
in the custom resource YAML file. -
Use a certificate and private key
The certificate and private key must be base64-encoded. To use this variant, add the following parameters to the custom resource YAML file:
agent.tls.certificate
agent.tls.key
If
agent.tls.secretName
is set, thenagent.tls.certificate
andagent.tls.key
are ignored.
-
-
If you want to deploy the static host agent, configure the custom resource YAML file with the static agent image. To list the static host agent image, set
agent.image.name
tocontainers.instana.io/instana/release/agent/static
. See the following example:spec: agent: image: name: containers.instana.io/instana/release/agent/static
-
Optional: You can replace the following values:
-
agent.env
: Use this field to specify environment variables for the agent, such as the proxy configuration for the agent. For more possible environment values, see agent configuration. See the following example:spec: agent: env: INSTANA_AGENT_TAGS: staging
-
agent.configuration_yaml
: Use this field to specify an agent configuration fileconfiguration.yaml
. See the following example:spec: agent: configuration_yaml: | # Example of configuration yaml template # Host com.instana.plugin.host: tags: - 'dev' - 'app1'
For more information, see Configuring host agents by using the agent configuration file.
-
-
-
Apply the custom resource YAML file:
kubectl apply -f instana-agent.customresource.yaml
Where
instana-agent.customresource.yaml
is the name of your custom resource YAML file.The Operator picks up the configuration from the custom resource YAML file and deploys the Instana agent.
The agent is installed. For more information about the next steps, see to the What to do next section.
To update the agent, see Updating an operator installation.
Install by using the Helm chart
You can use the Helm chart to install the agent. The Helm chart adds the Instana agent to all worker nodes that can be used to schedule workload in your cluster by using a DaemonSet.
To install the Instana agent using a Helm chart, you must first install or upgrade your local helm
CLI to version 3.
The Instana agent Helm chart supports Red Hat OpenShift 4.x.
To install the agent by using Helm chart, complete the following steps:
-
On the home page of the Instana UI, click Deploy Agent.
-
On the agent deployment catalog page, click the tile Kubernetes - Helm chart.
-
Enter the cluster name and (optionally) the agent zone that you want the cluster to be part of.
The cluster name (
<your_cluster_name>
) is the customized name of the cluster, which is monitored by this daemonset.The agent zone (
<your_zone_name>
) is used to customize the zone grouping, which is displayed on the infrastructure map.The agent deployment code is updated with the values that you provide. All of the other required parameters are pre-populated in the agent deployment code, which looks like the following example:
helm install instana-agent --repo https://agents.instana.io/helm \ --namespace instana-agent \ --create-namespace \ --set agent.key='<your_agent_key>' \ --set agent.endpointHost='<your_host_agent_endpoint>' \ --set agent.endpointPort=443 \ --set cluster.name='<your_cluster_name>' \ --set zone.name='<your_zone_name>' \ instana-agent
-
Edit the agent deployment code:
To configure the installation, you can specify the values on the command line by using the
--set
flag or provide a YAML file with your values by using the-f
flag. For a detailed list of all the configuration parameters, see Instana Helm chart.-
If you want to deploy the static host agent, set the flag
--set agent.image.name=containers.instana.io/instana/release/agent/static
. -
If you want to set up TLS encryption for the agent endpoint, use an existing secret or use a certificate and private key:
-
Use an existing secret of type
kubernetes.io/tls
You can use an existing secret of the type
kubernetes.io/tls
for TLS encryption. But you must specify thesecretName
with--set 'agent.tls.secretName=<YOUR_SECRET_NAME>'
during installation. The files from the provided secret is then included in the agent. -
Use a certificate and private key
The certificate and private key must be base64-encoded. To use this variant, run
helm install
with the following extra parameters:--set 'agent.tls.certificate=<YOUR_CERTIFICATE_BASE64_ENCODED>' --set 'agent.tls.key=<YOUR_PRIVATE_KEY_BASE64_ENCODED>'
If
agent.tls.secretName
is set, thenagent.tls.certificate
andagent.tls.key
are ignored.
-
-
-
Copy and then run the agent deployment code.
The agent is installed. For more information about the next steps, see to the What to do next section.
To update the agent, see Updating an operator installation.
Install by using a static YAML file
Installing the Instana agent by using static YAML is not suggested because it is no longer updated. Instead, you are suggested to install the agent by using the Instana agent operator.
To install the agent by using a YAML file, complete the following steps:
-
On the home page of the Instana UI, click Deploy Agent.
-
On the agent deployment catalog page, click the tile Kubernetes - YAML.
-
Enter the cluster name and (optionally) the agent zone that you want the cluster to be part of.
The cluster name (
<your_cluster_name>
) is the customized name of the cluster that is monitored by this daemonset.The agent zone (
<your_zone_name>
) is used to customize the zone grouping, which is displayed on the infrastructure map.The agent deployment code is updated with the values that you provide. All of the other required parameters are pre-populated in the agent deployment code.
-
Create a custom resource YAML file by copying the YAML template provided in the Instana UI. For example:
deployment.yaml
.The YAML template is pre-filled with your agent key, host agent endpoint, cluster name, and agent zone.4
-
Edit the YAML file based on your needs:
-
Instana host agent requires the
privileged
Pod Security Standard. To enforce the Pod Security Standard with a built-in Pod Security Admission controller, run the following command:kubectl label --overwrite ns instana-agent pod-security.kubernetes.io/enforce=privileged
-
Optional: To deploy for Kubernetes versions before 1.8 with RBAC enabled, replace
rbac.authorization.k8s.io/v1
withrbac.authorization.k8s.io/v1beta1
for RBAC api version.To grant your user the ability to create authorization roles, for example in Google Kubernetes Engine (GKE), run this command:
kubectl create clusterrolebinding cluster-admin-binding \ --clusterrole cluster-admin --user $(gcloud config get-value account)
If you don't enable RBAC, you need to remove
ClusterRole
andClusterRoleBinding
from theinstana-agent.yaml
file. -
Optional: To enable a PodSecurityPolicy for the Instana agent, complete the following steps:
-
Create a
PodSecurityPolicy
resource as defined in Helm chart. -
Authorize that policy in the
instana-agent
ClusterRole
. You need to enable RBAC with theClusterRole
andClusterRoleBinding
resources that are created in the previously mentionedinstana-agent.yaml
file. -
Enable the PodSecurityPolicy admission controller in your cluster. For existing clusters, you are recommended to add and authorize policies before you enable the admission controller.
-
-
-
Install the agent within your Kubernetes cluster by running the following command:
kubectl apply -f deployment.yaml
Where
deployment.yaml
is the name of the YAML file that you created in the previous step.If you make any more edits to the
deployment.yaml
file, you must re-create the DaemonSet by running the following commands:kubectl delete -f deployment.yaml
kubectl apply -f deployment.yaml
The agent is installed. For more information about the next steps, see to the What to do next section.