Installing the Agent

Describes the various ways your clusters can be connected to the TLSPK platform through the agent

Installation

The TLSPK agent can be installed through multiple methods. Installing through the dashboard or jsctl can be more convenient for quick demo, dev or exploration use cases.

We recommend the helm installation method for the production configuration of your clusters with the TLSPK platform.

Note that you will need cluster level access as part of this installation.

TLSPK UI installation:

To install the agent, sign in to TLS Protect for Kubernetes and navigate to Clusters > Connect New Cluster. Enter a name for the cluster, and then follow the instructions to apply the generated configuration.

jsctl CLI installation:

1. Obtain the jsctl binary from our releases page
2. Log in to TLSPK with the CLI: jsctl auth login
3. Set your organization: jsctl configuration set organization <org-name>
4. Connect your cluster: jsctl cluster connect <cluster-name>

jetstack-agent helm chart installation:

Using chart installation, there are two credentials required.

• A credential to allow helm to pull the chart from our registry.
• An agent credential used by the agent to authenticate to TLSPK.

1) Obtain OCI registry credentials

The helm chart is an OCI chart artifact hosted on both EU and US registries:

• oci://eu.gcr.io/jetstack-secure-enterprise/charts/jetstack-agent
• oci://us.gcr.io/jetstack-secure-enterprise/charts/jetstack-agent

More detailed instructions on how to access our registry are available in this guide

For chart installation, run the following to set a registry configuration file, so helm can authenticate to our private OCI registry:

export TLSPK_DOCKER_CONFIG_PATH="$(pwd)"
export TLSPK_DOCKER_CONFIG_FILE="${TLSPK_DOCKER_CONFIG_PATH}/config.json"
jsctl registry auth output --format=dockerconfig > "${TLSPK_DOCKER_CONFIG_FILE}"

To validate you registry credentials are working with helm, we can use it to show us the full list of values available to configure the chart:

helm show values oci://eu.gcr.io/jetstack-secure-enterprise/charts/jetstack-agent --registry-config "${TLSPK_DOCKER_CONFIG_FILE}"

2) Obtaining TLSPK agent credentials:

Set the following environments variables for ease of installation:

export TLSPK_ORG="<ORG_NAME>"
export TLSPK_CLUSTER_NAME="<CLUSTER_NAME>"

Obtain your service account credential, this can be done through the UI or jsctl

For example with jsctl:

jsctl auth login
jsctl set organization ${TLSPK_ORG}
jsctl auth clusters create-service-account ${TLSPK_CLUSTER_NAME} | tee credentials.json

Store this carefully as we will need it to create a Kubernetes secret in the installation cluster.

3) Deploying the chart:

Once credentials are obtained, there are two ways to install the chart:

Option 1 (Recommended): Create secret manually

Use the credential obtained in the previous step to create the secret in cluster:

kubectl create secret generic agent-credentials --namespace jetstack-secure --from-file=credentials.json

Install the chart with the basic configuration:

helm upgrade --install --create-namespace -n jetstack-secure jetstack-agent \
  oci://eu.gcr.io/jetstack-secure-enterprise/charts/jetstack-agent \
  --registry-config "${TLSPK_DOCKER_CONFIG_FILE}" \
  --set config.organisation="${TLSPK_ORG}" \
  --set config.cluster="${TLSPK_CLUSTER_NAME}"

Option 2 (Not Recommended): Create secret with helm chart install

Set this environment variable to contain the encoded agent credential:

export HELM_SECRET="$(cat credentials.json | base64 -w0)"

Installing the chart with additional configuration options for the agents credential, read from the environment variable just set:

helm upgrade --install --create-namespace -n jetstack-secure jetstack-agent \
  oci://eu.gcr.io/jetstack-secure-enterprise/charts/jetstack-agent \
  --registry-config "${TLSPK_DOCKER_CONFIG_FILE}" \
  --set config.organisation="${TLSPK_ORG}" \
  --set config.cluster="${TLSPK_CLUSTER_NAME}" \
  --set authentication.createSecret=true \
  --set authentication.secretValue="${HELM_SECRET}"

4) Deployment Verification

Check the agent logs to ensure you see a similar entry to the following:

2023/04/19 14:11:41 Running Agent...
2023/04/19 14:11:41 Posting data to: https://platform.jetstack.io
2023/04/19 14:11:42 Data sent successfully.

You can do this with the following command:

kubectl logs -n jetstack-secure $(kubectl get pod -n jetstack-secure -l app.kubernetes.io/instance=jetstack-agent -o jsonpath='{.items[0].metadata.name}')

Known Issues

Unique Cluster Naming

With the cluster name, ensure you are not reusing a previous value as these must be unique within the lifetime of an organization. For example if you created example_1 as the cluster name, that name cannot be used again, even if the cluster is removed from the organization.

For short lived clusters such as demos you could use a date string to ensure the cluster is unique, for example:

export TLSPK_CLUSTER_NAME="demo_tlspk_$(date +"%Y%m%d_%H%M")"

Uninstall

Removing the agent will vary based on your installation method.

TLSPK UI / jsctl uninstall

kubectl delete clusterrolebinding jetstack-secure-agent-awspca-reader jetstack-secure-agent-cert-manager-reader jetstack-secure-agent-cluster-viewer jetstack-secure-agent-get-webhooks jetstack-secure-agent-googlecas-reader jetstack-secure-agent-istio-reader jetstack-secure-agent-node-reader jetstack-secure-agent-secret-reader jetstack-secure-agent-venafi-enhanced-read
kubectl delete clusterrole jetstack-secure-agent-awspca-reader jetstack-secure-agent-cert-manager-reader jetstack-secure-agent-get-webhooks jetstack-secure-agent-googlecas-reader jetstack-secure-agent-istio-reader jetstack-secure-agent-node-reader jetstack-secure-agent-secret-reader jetstack-secure-agent-venafi-enhanced-reader
kubectl delete deploy agent
kubectl delete cm agent-config
kubectl delete sa agent
kubectl delete secret agent-credentials
kubectl delete ns jetstack-secure

helm uninstall

helm uninstall -n jetstack-secure jetstack-agent
kubectl delete secret -n jetstack-secure agent-credentials
kubectl delete ns jetstack-secure