Self-Hosted Kubernetes Agent

​

Requirements

• Kubernetes cluster at version >= 1.24
  • Autoscaler
  • Persistent Volume/Storage Class(Optional)
  • AMD64 or ARM64-based nodes.
• The agent will be installed using a Helm chart.

​

Autoscaler (recommended, but optional)

• While optional, configuring horizontal auto-scaling will allow your cluster to adapt to the concurrency and deployment requirements based on your env zero usage. Otherwise, your deployment concurrency will be limited by the cluster’s capacity. Please also see Job Limits if you wish you to control the maximum concurrent deployment.
• The env zero agent will create a new pod for each deployment you run on env zero.
  Pods are ephemeral and will be destroyed after a single deployment.
• A pod running a single deployment requires at least cpu: 460m and memory: 1500Mi, so the cluster nodes must be able to provide this resource request. Limits can be adjusted by providing custom configuration during chart installation.
• Minimum node requirements: an instance with at least 2 CPU and 8GiB memory.

​

Persistent Volume/Storage Class (optional)

• env zero will store the deployment state and working directory on a persistent volume in the cluster.
• Must support Dynamic Provisioning and ReadWriteMany access mode.
• The requested storage space is 300Gi.
• The cluster must include a StorageClass named env0-state-sc.
• The Storage Class should be set up with reclaimPolicy: Retain, to prevent data loss in case the agent needs to be replaced or uninstalled.

​

Sensitive Secrets

• Using secrets stored on the env zero platform is not allowed for self-hosted agents, since self-hosted agents allow you to store secrets on your own infrastructure.
• Customers using self-hosted agents may use their own Kubernetes Secret to store sensitive values - see env0ConfigSecretName below.
• If you are migrating from SaaS to a self-hosted agent, deployments attempting to use these secrets will fail.
• This includes sensitive configuration variables, SSH keys, and Cloud Deployment credentials. The values for these secrets should be replaced with references to your secret store, as detailed in the table below.
• In order to use an external secret store, authentication to the secret store must be configured using a custom Helm values file. The required parameters are detailed in Custom/Optional Configuration.
• Storing secrets is supported using these secret stores:

​

Custom/Optional Configuration

​

Further Configuration

​

Job Limits

​

Installation

1. Add our Helm Repo
   helm repo add env0 https://env0.github.io/self-hosted
   
2. Update Helm Repo
   helm repo update
   
3. Get your agent access token by creating an agent pool in the env zero UI.
4. Install the Helm Charts
   helm install --create-namespace env0-agent env0/env0-agent --namespace env0-agent --set-string agentAccessToken='<your-agent-access-token>' -f values.customer.yaml
   # values.customer.yaml should contain any optional configuration options as detailed above
   

# Create agent pool and install agent using helm chart

variable "agent_custom_configuration" {
  type        = map(any)
  description = "See https://docs.envzero.com/guides/admin-guide/self-hosted-kubernetes-agent/custom-optional-configuration"
}

resource "env0_agent_pool" "default" {
  name = "default self-hosted agent"
}

resource "env0_agent_secret" "first" {
  agent_id = env0_agent_pool.default.id
}

resource "helm_release" "this" {
  repository = "https://env0.github.io/self-hosted"
  chart      = "env0-agent"

  namespace = "env0-agent-default"
  name      = "env0-agent-default"

  create_namespace = true
  timeout          = 600

  set_sensitive {
    name  = "agentAccessToken"
    value = env0_agent_secret.first.secret
  }

  values = [
    yamlencode(var.agent_custom_configuration)
  ]
}

​

Upgrade

helm upgrade env0-agent env0/env0-agent --namespace env0-agent

​

Verify Installation/Upgrade

helm test env0-agent --namespace env0-agent --logs --timeout 1m

​

Using the helm template command

helm repo add env0 https://env0.github.io/self-hosted
helm repo update

helm template env0-agent env0/env0-agent --kube-version=<KUBERNETES_VERSION> --api-version=batch/v1/CronJob -n <MY_NAMESPACE> --set-string agentAccessToken='<your-agent-access-token>' -f values.customer.yaml

helm template env0-agent env0/env0-agent --kube-version=<KUBERNETES_VERSION> -n <MY_NAMESPACE> --set-string agentAccessToken='<your-agent-access-token>' -f values.customer.yaml

• <KUBERNETES_VERSION> is the version of your kubernetes cluster
• <MY_NAMESPACE> is the k8s namespace in which the agent will be installed
• values.customer.yaml is your custom values file for additional configuration options.

​

🌐 Required Outbound Domains

💡 Note: All domains listed above require outbound HTTPS (port 443) access from the env zero agent.
Only open access to the domains for the features you are actually using.