Automated Installation

Automated installation via Terraform

The Kubernetes Agent can be installed and managed using a combination of the Kubernetes Agent Helm chart >= v2.2.1, Octopus Deploy >= v0.30.0 Terraform provider and/or Helm Terraform provider.

Octopus Deploy & Helm

Using a combination of the Octopus Deploy and Helm providers you can completely manage the Kubernetes Agent via Terraform.

terraform {
  required_providers {
    octopusdeploy = {
      source = "OctopusDeploy/octopusdeploy"
      version = "1.7.1"
    }

    helm = {
      source  = "registry.terraform.io/hashicorp/helm"
      version = "3.1.1"
    }
  }
}

locals {
  octopus_api_key         = "API-XXXXXXXXXXXXXXXX"
  octopus_address         = "https://myinstance.octopus.app"
  octopus_grpc_address    = "https://myinstance.octopus.app:8443"
  octopus_polling_address = "https://polling.myinstance.octopus.app"
}

provider "octopusdeploy" {
  address = local.octopus_address
  api_key = local.octopus_api_key
}

provider "helm" {
  kubernetes = {
    # Configure authentication for me
  }
}

data "octopusdeploy_teams" "everyone" {
  partial_name = "Everyone"
  skip         = 0
  take         = 1
}

resource "octopusdeploy_space" "monitoring" {
  name                 = "Kubernetes Examples"
  description          = "Terraform created examples"
  space_managers_teams = [data.octopusdeploy_teams.everyone.teams[0].id]
}

resource "octopusdeploy_environment" "example" {
  name     = "Example"
  space_id = octopusdeploy_space.monitoring.id
}

# Create the Kubernetes agent deployment target
resource "octopusdeploy_polling_subscription_id" "agent_subscription_id" {}
resource "octopusdeploy_tentacle_certificate" "agent_cert" {}
resource "octopusdeploy_kubernetes_agent_deployment_target" "example" {
  name         = "Example Kubernetes Agent"
  space_id     = octopusdeploy_space.monitoring.id
  environments = [octopusdeploy_environment.example.id]
  roles        = ["k8s-agent", "monitoring-enabled"]

  thumbprint = octopusdeploy_tentacle_certificate.agent_cert.thumbprint
  uri        = octopusdeploy_polling_subscription_id.agent_subscription_id.polling_uri
}

# Create the Kubernetes monitor
resource "random_uuid" "monitor_installation" {}
resource "octopusdeploy_kubernetes_monitor" "example" {
  space_id        = octopusdeploy_space.monitoring.id
  installation_id = random_uuid.monitor_installation.result
  machine_id      = octopusdeploy_kubernetes_agent_deployment_target.example.id
}

# Install the Kubernetes agent and monitor via Helm
resource "helm_release" "kubernetes_agent" {
  name             = "example-kubernetes-agent"
  repository       = "oci://registry-1.docker.io"
  chart            = "octopusdeploy/kubernetes-agent"
  version          = "2.*.*"
  atomic           = true
  create_namespace = true
  namespace        = "octopus-agent-example"

  set = [
    {
      name  = "agent.acceptEula"
      value = "Y"
    },
    {
      name  = "agent.name"
      value = octopusdeploy_kubernetes_agent_deployment_target.example.name
    },
    {
      name  = "agent.serverUrl"
      value = local.octopus_address
    },
    {
      name  = "agent.serverCommsAddress"
      value = local.octopus_polling_address
    },
    {
      name  = "agent.serverSubscriptionId"
      value = octopusdeploy_polling_subscription_id.agent_subscription_id.polling_uri
    },
    {
      name  = "agent.space"
      value = octopusdeploy_space.monitoring.name
    },
    {
      name  = "agent.deploymentTarget.enabled"
      value = "true"
    },

    # Kubernetes monitor configuration (optional)
    {
      name  = "kubernetesMonitor.enabled"
      value = "true"
    },
    {
      name  = "kubernetesMonitor.registration.register"
      value = "false"
    },
    {
      name  = "kubernetesMonitor.monitor.serverGrpcUrl"
      value = local.octopus_grpc_address
    },
    {
      name  = "kubernetesMonitor.monitor.installationId"
      value = octopusdeploy_kubernetes_monitor.example.installation_id
    },
    {
      name  = "kubernetesMonitor.monitor.serverThumbprint"
      value = octopusdeploy_kubernetes_monitor.example.certificate_thumbprint
    }
  ]

  set_sensitive = [
    {
      name  = "agent.serverApiKey"
      value = local.octopus_api_key
    },
    {
      name  = "agent.certificate"
      value = octopusdeploy_tentacle_certificate.agent_cert.base64
    },
    {
      name  = "kubernetesMonitor.monitor.authenticationToken"
      value = octopusdeploy_kubernetes_monitor.example.authentication_token
    }
  ]

  set_list = [
    {
      name  = "agent.deploymentTarget.initial.environments"
      value = octopusdeploy_kubernetes_agent_deployment_target.example.environments
    },
    {
      name  = "agent.deploymentTarget.initial.tags"
      value = octopusdeploy_kubernetes_agent_deployment_target.example.roles
    }
  ]
}

Helm

The Kubernetes Agent can be installed using just the Helm provider alone. However, the associated deployment target that is created in Octopus cannot be managed solely using the Helm provider. This is because the Helm chart values relating to the agent are only used on initial installation. Any further modifications to them will not trigger an update to the deployment target unless you perform a complete reinstall of the agent.

If you don’t intend to manage the Kubernetes Agent configuration through Terraform (choosing to handle it via the Octopus Portal or API instead), this option will be beneficial to you as it is simpler to set up.

terraform {
  required_providers {
    helm = {
      source  = "registry.terraform.io/hashicorp/helm"
      version = "3.1.1"
    }
  }
}

locals {
  octopus_api_key         = "API-XXXXXXXXXXXXXXXX"
  octopus_address         = "https://myinstance.octopus.app"
  octopus_grpc_address    = "https://myinstance.octopus.app:8443"
  octopus_polling_address = "https://polling.myinstance.octopus.app"
}

provider "helm" {
  kubernetes = {
    # Configure authentication for me
  }
}

# Install the Kubernetes agent and monitor via Helm
resource "helm_release" "kubernetes_agent" {
  name             = "example-kubernetes-agent"
  repository       = "oci://registry-1.docker.io"
  chart            = "octopusdeploy/kubernetes-agent"
  version          = "2.*.*"
  atomic           = true
  create_namespace = true
  namespace        = "octopus-agent-example"

  set = [
    {
      name  = "agent.acceptEula"
      value = "Y"
    },
    {
      name  = "agent.name"
      value = "octopus-agent"
    },
    {
      name  = "agent.serverUrl"
      value = local.octopus_address
    },
    {
      name  = "agent.serverCommsAddress"
      value = local.octopus_polling_address
    },
    {
      name  = "agent.space"
      value = "Default"
    },
    {
      name  = "agent.deploymentTarget.enabled"
      value = "true"
    }
  ]

  set_sensitive = [
    {
      name  = "agent.serverApiKey"
      value = local.octopus_api_key
    }
  ]

  set_list = [
    {
      name  = "agent.deploymentTarget.initial.environments"
      value = ["Development"]
    },
    {
      name  = "agent.deploymentTarget.initial.tags"
      value = ["k8s-agent"]
    }
  ]
}

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Thursday, January 15, 2026