diff --git a/public/docs/i/1000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp b/public/docs/i/1000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp new file mode 100644 index 0000000000..2870581ee0 Binary files /dev/null and b/public/docs/i/1000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp differ diff --git a/public/docs/i/1000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp b/public/docs/i/1000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp new file mode 100644 index 0000000000..03bce26fc0 Binary files /dev/null and b/public/docs/i/1000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp differ diff --git a/public/docs/i/1000/octopus-ai-assistant/recovery-agent-optout-envvar.webp b/public/docs/i/1000/octopus-ai-assistant/recovery-agent-optout-envvar.webp new file mode 100644 index 0000000000..7ca2e4037d Binary files /dev/null and b/public/docs/i/1000/octopus-ai-assistant/recovery-agent-optout-envvar.webp differ diff --git a/public/docs/i/1000/octopus-ai/assistant/restrict-access.webp b/public/docs/i/1000/octopus-ai/assistant/restrict-access.webp new file mode 100644 index 0000000000..2ebbbc638e Binary files /dev/null and b/public/docs/i/1000/octopus-ai/assistant/restrict-access.webp differ diff --git a/public/docs/i/2000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp b/public/docs/i/2000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp new file mode 100644 index 0000000000..2870581ee0 Binary files /dev/null and b/public/docs/i/2000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp differ diff --git a/public/docs/i/2000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp b/public/docs/i/2000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp new file mode 100644 index 0000000000..03bce26fc0 Binary files /dev/null and b/public/docs/i/2000/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp differ diff --git a/public/docs/i/2000/octopus-ai-assistant/recovery-agent-optout-envvar.webp b/public/docs/i/2000/octopus-ai-assistant/recovery-agent-optout-envvar.webp new file mode 100644 index 0000000000..10b91a9e19 Binary files /dev/null and b/public/docs/i/2000/octopus-ai-assistant/recovery-agent-optout-envvar.webp differ diff --git a/public/docs/i/2000/octopus-ai/assistant/restrict-access.webp b/public/docs/i/2000/octopus-ai/assistant/restrict-access.webp new file mode 100644 index 0000000000..770b591507 Binary files /dev/null and b/public/docs/i/2000/octopus-ai/assistant/restrict-access.webp differ diff --git a/public/docs/i/600/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp b/public/docs/i/600/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp new file mode 100644 index 0000000000..2870581ee0 Binary files /dev/null and b/public/docs/i/600/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.webp differ diff --git a/public/docs/i/600/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp b/public/docs/i/600/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp new file mode 100644 index 0000000000..be0191d20d Binary files /dev/null and b/public/docs/i/600/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.webp differ diff --git a/public/docs/i/600/octopus-ai-assistant/recovery-agent-optout-envvar.webp b/public/docs/i/600/octopus-ai-assistant/recovery-agent-optout-envvar.webp new file mode 100644 index 0000000000..4e8f0aff60 Binary files /dev/null and b/public/docs/i/600/octopus-ai-assistant/recovery-agent-optout-envvar.webp differ diff --git a/public/docs/i/600/octopus-ai/assistant/restrict-access.webp b/public/docs/i/600/octopus-ai/assistant/restrict-access.webp new file mode 100644 index 0000000000..9418fce0f9 Binary files /dev/null and b/public/docs/i/600/octopus-ai/assistant/restrict-access.webp differ diff --git a/public/docs/i/x/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png b/public/docs/i/x/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png new file mode 100644 index 0000000000..5c2af3a1e9 Binary files /dev/null and b/public/docs/i/x/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png differ diff --git a/public/docs/i/x/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png b/public/docs/i/x/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png new file mode 100644 index 0000000000..32378a1fdf Binary files /dev/null and b/public/docs/i/x/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png differ diff --git a/public/docs/i/x/octopus-ai-assistant/recovery-agent-optout-envvar.png b/public/docs/i/x/octopus-ai-assistant/recovery-agent-optout-envvar.png new file mode 100644 index 0000000000..77ff667e53 Binary files /dev/null and b/public/docs/i/x/octopus-ai-assistant/recovery-agent-optout-envvar.png differ diff --git a/public/docs/i/x/octopus-ai/assistant/restrict-access.png b/public/docs/i/x/octopus-ai/assistant/restrict-access.png new file mode 100644 index 0000000000..bdc5e00721 Binary files /dev/null and b/public/docs/i/x/octopus-ai/assistant/restrict-access.png differ diff --git a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-advanced-settings.png b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-advanced-settings.png index b921963ed2..a47acfb6b5 100644 Binary files a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-advanced-settings.png and b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-advanced-settings.png differ diff --git a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png new file mode 100644 index 0000000000..dcc34e0e8e Binary files /dev/null and b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png differ diff --git a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png.json b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png.json new file mode 100644 index 0000000000..a7e86fdbf6 --- /dev/null +++ b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png.json @@ -0,0 +1 @@ +{"width":480,"height":414,"updated":"2026-04-30T02:13:27.333Z"} \ No newline at end of file diff --git a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png new file mode 100644 index 0000000000..51557454b2 Binary files /dev/null and b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png differ diff --git a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png.json b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png.json new file mode 100644 index 0000000000..d59b59c39b --- /dev/null +++ b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png.json @@ -0,0 +1 @@ +{"width":906,"height":639,"updated":"2026-04-30T02:13:27.360Z"} \ No newline at end of file diff --git a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-wizard-config.png b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-wizard-config.png index da9b4c9475..fd8fee556c 100644 Binary files a/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-wizard-config.png and b/public/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-wizard-config.png differ diff --git a/public/docs/img/octopus-ai-assistant/recovery-agent-optout-envvar.png.json b/public/docs/img/octopus-ai-assistant/recovery-agent-optout-envvar.png.json new file mode 100644 index 0000000000..18c807eca7 --- /dev/null +++ b/public/docs/img/octopus-ai-assistant/recovery-agent-optout-envvar.png.json @@ -0,0 +1 @@ +{"width":1593,"height":920,"updated":"2026-04-30T01:36:24.553Z"} \ No newline at end of file diff --git a/public/docs/img/octopus-ai/assistant/restrict-access.png.json b/public/docs/img/octopus-ai/assistant/restrict-access.png.json new file mode 100644 index 0000000000..084c1eadc3 --- /dev/null +++ b/public/docs/img/octopus-ai/assistant/restrict-access.png.json @@ -0,0 +1 @@ +{"width":3456,"height":1828,"updated":"2026-04-30T01:36:24.452Z"} \ No newline at end of file diff --git a/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md b/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md index 12b787d05a..c72523c878 100644 --- a/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md +++ b/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2024-04-22 -modDate: 2026-01-15 +modDate: 2026-04-30 title: Kubernetes agent navTitle: Overview navSection: Kubernetes agent @@ -43,7 +43,7 @@ When you install the agent, several resources will be created within a cluster, - Certain resource names may vary based on the target name and any overrides. -- The NFS section to the right is created only when a user-defined storageClassName is not included. +- The NFS section to the right is only relevant for pre-version v3 of the agent - `tentacle-certificate` is only created if you provide your own certificate during installation. @@ -75,17 +75,22 @@ Upon completion of the task, the pod will terminate itself. The Kubernetes agent follows [semantic versioning](https://semver.org/), so a major agent version is locked to a Octopus Server version range. Updating to the latest major agent version requires updating to a supported Octopus Server. The supported versions for each agent major version are: -| Kubernetes agent | Octopus Server | Kubernetes cluster | -| ---------------- | ------------------------ | -------------------- | -| 1.0.0 - 1.16.1 | **2024.2.6580** or newer | **1.26** to **1.29** | -| 1.17.0 - 1.19.2 | **2024.2.6580** or newer | **1.27** to **1.30** | -| 1.20.0 - 1.21.0 | **2024.2.6580** or newer | **1.28** to **1.31** | -| 1.22.0 - 1.\*.\* | **2024.2.6580** or newer | **1.29** to **1.32** | -| 2.0.0 - 2.2.1 | **2024.2.9396** or newer | **1.26** to **1.29** | -| 2.3.0 - 2.8.2 | **2024.2.9396** or newer | **1.27** to **1.30** | -| 2.9.0 - 2.11.3 | **2024.2.9396** or newer | **1.28** to **1.31** | -| 2.12.0 - 2.25.1 | **2024.2.9396** or newer | **1.29** to **1.32** | -| 2.26.0 - 2.\*.\* | **2024.2.9396** or newer | **1.30** to **1.33** | +| Kubernetes agent | Octopus Server | Kubernetes cluster | +| ----------------- | -------------------------- | -------------------- | +| 1.0.0 - 1.16.1 | **2024.2.6580** or newer | **1.26** to **1.29** | +| 1.17.0 - 1.19.2 | **2024.2.6580** or newer | **1.27** to **1.30** | +| 1.20.0 - 1.21.0 | **2024.2.6580** or newer | **1.28** to **1.31** | +| 1.22.0 - 1.24.0 * | **2024.2.6580** or newer | **1.29** to **1.32** | +| 2.0.0 - 2.2.1 | **2024.2.9396** or newer | **1.26** to **1.29** | +| 2.3.0 - 2.8.2 | **2024.2.9396** or newer | **1.27** to **1.30** | +| 2.9.0 - 2.11.3 | **2024.2.9396** or newer | **1.28** to **1.31** | +| 2.12.0 - 2.25.1 | **2024.2.9396** or newer | **1.29** to **1.32** | +| 2.26.0 - 2.37.0 | **2024.2.9396** or newer | **1.30** to **1.33** | +| 2.38.1 - 2.\*.\* | **2024.2.9396** or newer | **1.30** to **1.33** | +| 3.0.0 - 3.\*.\* | **2024.2.9396** or newer † | **1.32** to **1.35** | + +\* Version 1 of the Kubernetes agent is not longer maintained. +† Version 3 of the Kubernetes agent of the Kubernetes agent is compatible with this version, however it is only prompted as the installed version in **2026.2.7054** or newer. Additionally, the Kubernetes agent only supports **Linux AMD64** and **Linux ARM64** Kubernetes nodes. @@ -121,6 +126,8 @@ kubectl config view 2. Select at least one [environment](/docs/infrastructure/environments) for the target. 3. Select at least one [target tag](/docs/infrastructure/deployment-targets/target-tags) for the target. 4. Optionally, set the default namespace that resources are deployed to. This is only used if the step configuration or Kubernetes manifests don't specify a namespace. +5. Optionally, add the name of an existing [Storage Class](https://kubernetes.io/docs/concepts/storage/storage-classes/) for the agent to use. If the storage class supports the `ReadWriteMany` [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) and you wish to scale horizontally, check the checkbox below the storage class. +If no storage class name is added, the default cluster storage class with `ReadWriteOnce` access mode will be used. :::div{.warning} As the display name is used for the Helm release name, this name must be unique for a given cluster. This means that if you have a Kubernetes agent and Kubernetes worker with the same name (e.g. `production`), then they will clash during installation. @@ -136,28 +143,6 @@ If you do want a Kubernetes agent and Kubernetes worker to have the same name, T Choose if you want to install additional components, such as the [Kubernetes monitor](/docs/kubernetes/targets/kubernetes-agent/kubernetes-monitor) or the [Permissions controller](/docs/kubernetes/targets/kubernetes-agent/granular-permissions) -Optionally, add the name of an existing [Storage Class](https://kubernetes.io/docs/concepts/storage/storage-classes/) for the agent to use. The storage class must support the ReadWriteMany [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). -If no storage class name is added, the default Network File System (NFS) storage will be used. - -### NFS CSI driver - -If no [Storage Class](https://kubernetes.io/docs/concepts/storage/storage-classes/) name is set, the default NFS storage pod will be used. This runs a small NFS pod next to the agent pod and provides shared storage to the agent and script pods. - -A requirement of using the NFS pod is the installation of the [NFS CSI Driver](https://github.com/kubernetes-csi/csi-driver-nfs). This can be achieved by executing the presented helm command in a terminal connected to the target Kubernetes cluster. - -:::figure -![Kubernetes Agent Wizard NFS CSI Page](/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-wizard-nfs.png) -::: - -:::div{.warning} -If you receive an error with the text `failed to download` or `no cached repo found` when attempting to install the NFS CSI driver via helm, try executing the following command and then retrying the install command: - -```bash -helm repo update -``` - -::: - ### Installation helm command At the end of the wizard, Octopus generates a Helm command that you copy and paste into a terminal connected to the target cluster. After it's executed, Helm installs all the required resources and starts the agent. @@ -310,6 +295,22 @@ This image contains the minimum required tooling to run Kubernetes workloads for - `helm` - `powershell` +## Modifying the Helm installation + +The Helm installation of the Kubernetes agent can be modified after installation if changes to the installed values need to be made. To help facilitate this, there is a dialog that can be launched that gives a pre-populated Helm command where additional values can be set. + +It is launched from the contedt menu on the Kubernetes agent settings page which can be navigated to **Infrastructure ➜ Deployment Targets ➜ [DEPLOYMENT TARGET] ➜ Settings**. + +:::figure +![Kubernetes Agent Modify via Helm context menu item](/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-context-menu.png) +::: + +Once launched, it presents a dialog prefilled with the correct namespace and helm release name. From there, this command can be modified, copied and executed in a terminal connected to the cluster. + +:::figure +![Kubernetes Agent Modify via Helm dialog](/docs/img/infrastructure/deployment-targets/kubernetes/kubernetes-agent/kubernetes-agent-modify-via-helm-dialog.png) +::: + ## Upgrading the Kubernetes agent The Kubernetes agent can be upgraded automatically by Octopus Server, manually in the Octopus portal or via a `helm` command. diff --git a/src/pages/docs/kubernetes/targets/kubernetes-agent/troubleshooting/version-specific-notes.md b/src/pages/docs/kubernetes/targets/kubernetes-agent/troubleshooting/version-specific-notes.md new file mode 100644 index 0000000000..d1f5cff5ed --- /dev/null +++ b/src/pages/docs/kubernetes/targets/kubernetes-agent/troubleshooting/version-specific-notes.md @@ -0,0 +1,33 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-04-30 +modDate: 2026-04-30 +title: Version specific notes +description: Contains a list of version specific notes +navOrder: 72 +--- + +## Version 2 + +### NFS CSI driver + +:::div{.hint} +With the release of V3 of the agent, this is no longer required in the default installation. However, if you want to continue using the NFS storage with the v3 agent, you will need to install the NFS CSI driver. +::: + +If no [Storage Class](https://kubernetes.io/docs/concepts/storage/storage-classes/) name is set, the default NFS storage pod will be used. This runs a small NFS pod next to the agent pod and provides shared storage to the agent and script pods. + +A requirement of using the NFS pod is the installation of the [NFS CSI Driver](https://github.com/kubernetes-csi/csi-driver-nfs). This can be achieved by executing the following helm command in a terminal connected to the target Kubernetes cluster. + +```bash +helm upgrade --install --atomic --repo https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/charts --namespace kube-system --version "v4.*.*" csi-driver-nfs csi-driver-nfs +``` + +:::div{.warning} +If you receive an error with the text `failed to download` or `no cached repo found` when attempting to install the NFS CSI driver via helm, try executing the following command and then retrying the install command: + +```bash +helm repo update +``` + +:::