First Kubernetes deployment

👋 Welcome to Octopus Deploy!

This tutorial will help you complete your first deployment to Kubernetes with Octopus Deploy. We’ll walk you through the steps to deploy YAML files to your Kubernetes cluster.

Before you start

To follow this tutorial, you need:

GitHub repository

To start quickly, you can fork our sample GitHub repository, which includes pre-created YAML files. Follow the steps below to fork the repository:

  1. Navigate to the OctoPetShop repository.

Sample OctoPetShop GitHub repository

  1. In the top-right corner of the page, click FORK.
  2. Provide an Owner and repository name, for example OctoPetShop.
  3. Keep the Copy the master branch only checkbox selected.
  4. Click CREATE FORK.
  5. Wait for the process to complete (this should only take a few seconds).

Now you’re ready, let’s begin deploying your first application to Kubernetes.

Log in to Octopus

  1. Log in to your Octopus instance and click GET STARTED.

Get started welcome screen

Add project

Projects let you manage software applications and services, each with its deployment process.

  1. Give your project a descriptive name and click SAVE.

Octopus Deploy 'Add New Project' form with fields for project details.

Add environments

You’ll need an environment to deploy to.

Environments are how you organize your infrastructure into groups representing the different stages of your deployment pipeline. For example, Dev, Test, and Production.

  1. Select the environments you’d like to create and click SAVE.

Environment selection options and deployment lifecycle visuals

Project questionnaire (optional)

You have the option to fill out a short survey. This helps our team learn about the technologies our customers are using, which guides the future direction of Octopus. It should only take about 30 seconds to complete.

  1. Click SUBMIT, and you’ll be taken to your project.

Octopus Deploy interface displaying a questionnaire

Create deployment process

The next step is creating your deployment process. This is where you define the steps that Octopus uses to deploy your software.

  1. Click CREATE PROCESS to see the available deployment steps.

Deployment process page with a button to create the process.

Configure Deploy Kubernetes YAML step

  1. Select the Kubernetes filter and then add the Deploy Kubernetes YAML step.

Kubernetes steps in the Octopus Deploy process editor.

Step name

You can leave this as the default Deploy Kubernetes YAML.

Execution location

This step will run once on a worker on behalf of each deployment target.

Workers are machines that can execute tasks that don’t need to be run on the Octopus Server or individual deployment targets.

You’ll learn more about deployment targets later in this tutorial.

Worker Pool

Worker Pools are groups of Workers. When a task is assigned to a Worker, the task will be executed by one of the Workers in the pools you’ve configured.

  1. Select Runs on a worker from a specific pool.
  2. Select Hosted Ubuntu from the dropdown menu.

Worker Pool expander with 'Hosted Ubuntu' selected.

Target tags

Target tags (formerly target roles) select specific deployment targets in an environment. This step will run on all deployment targets with the tags you specify in this field.

  1. Add a new target tag by typing it into the field. For this example, we’ll use k8s.

Target tag selection expander with 'k8s' tag currently added.

After configuring your deployment process, you’ll assign deployment targets to this target tag.

Container image

Next, you configure this step to run inside an execution container.

  1. Select Runs inside a container, on a worker.

Container image expander with 'Runs inside a container, on a worker selected'.

Add container image registry feed

For a step running on a Worker, you can select a Docker image to execute the step inside of.

Since you don’t have a Docker Container Registry available yet, you need to add one by following the steps below:

  1. Click the External Feeds link (this will open a new window).
  2. Click the ADD FEED button and select Docker Container Registry from the Feed Type dropdown.

Library section in Octopus with options to add external feeds.

  1. Provide a name for your feed, for example Docker Hub.
  2. Enter the feed URL to the public Docker Hub registry, for example
  3. You can leave the registry path blank for this example.

Form to create a Docker container registry external feed.

  1. Provide your credentials for Docker Hub.
  2. Click SAVE AND TEST, and then type nginx into the package name field to test your external feed.

A search interface in Octopus to test the Docker Hub repository.

Close the window and return to configuring the Deploy Kubernetes YAML step.

Container image

  1. Click REFRESH and select Docker Hub as your Container Registry.
  2. Copy the latest Ubuntu-based image from the help text and paste it into the container image field.

Container image expander using the latest Ubuntu-based image.

YAML source

This step lets you get your YAML from 3 different sources:

  • Git repository (default)
  • Package
  • Inline script

Sourcing from a Git repository can streamline your deployment process by reducing the steps required to get your YAML into Octopus.

  1. Select Git Repository as your YAML source.

YAML source expander with Git repository selected

Git repository details

  1. Select Library and add a new Git credential by clicking the + icon.
  2. Click the ADD GIT CREDENTIAL button.
  3. Enter a name for your Git credential.
  4. Provide your GitHub username.

A section in the library interface that lets users create and manage Git credentials.

Generate GitHub personal access token now requires token-based authentication (this excludes GitHub Enterprise Server). Create a personal access token following the steps below or learn more in the GitHub documentation.

  1. Navigate to and log in to your account.
  2. Click your profile picture in the top right corner.
  3. Click SETTINGS.
  4. Scroll down to the bottom of the page and click DEVELOPER SETTINGS.
  5. Under Personal access tokens, click FINE-GRAINED TOKENS.
  7. Under Token name, enter a name for the token.
  8. Under Expiration, provide an expiration for the token.
  9. Select a Resource Owner.
  10. Under Repository Access, choose Only select repositories and select the OctoPetShop repository from the dropdown.
  11. Click REPOSITORY PERMISSIONS, scroll down to Contents and select Read-only.
  12. Scroll down to the Overview, and you should have 2 permissions for one of your repositories (contents and metadata).
  13. Click Generate token and copy the token.

A GitHub settings page where users can manage permissions for fine-grained tokens.

Git repository details

  1. Paste the token into Octopus’s personal access token field.
  2. Save your Git credential and return to the Deploy Kubernetes YAML step.
  3. Click the refresh icon next to the Select Git credential dropdown.
  4. Select the Git credential you created earlier.

Authentication expander with a Git repository selected from the library.

Repository URL

  1. Enter the full URL to the Git repository where you store the YAML files you want to deploy, for example

Repository URL expander where the user's YAML files are stored.

Branch settings

  1. Provide the default branch you want to use, for example master if you’re using the sample repo.


  1. Enter the relative path(s) to the YAML files you want to deploy to your cluster. If you’re using the sample repo, the path will be k8s/*.yaml.

The Paths expander that lets users specify the paths to their YAML files using glob patterns.

Kubernetes object status check

This feature gives you live status updates during deployment for all the Kubernetes objects you’re deploying.

  1. Keep the default Check that Kubernetes objects are running successfully option selected with the default timeout of 180 seconds.

Kubernetes object status check expander with the default option and timeout selected.

Structured configuration variables

This is an advanced feature that you can skip for this tutorial. Learn more about structured configuration variables in our docs.

Referenced packages

This is an advanced feature that you can skip for this tutorial. Learn more about references packages in our docs.


  1. Specify the namespace in the cluster where you want to deploy your YAML files, for example demo-namespace.

If the namespace doesn’t exist yet, Octopus will create it during the deployment.


You can set conditions for greater control over how each step in your deployment process gets executed.

You can skip all the fields under this section for your first deployment.

Save your step and then move on to the next section to add your Kubernetes deployment target.

Add a deployment target

With Octopus Deploy, you can deploy software to:

  • Kubernetes clusters
  • Microsoft Azure
  • AWS
  • Cloud regions
  • Windows servers
  • Linux servers
  • Offline package drops

Wherever you’re deploying your software, these machines and services are known as your deployment targets.

  1. Navigate to InfrastructureDeployment Targets, and click ADD DEPLOYMENT TARGET.

Deployment targets page with no targets added.

  1. Select KUBERNETES CLUSTER and click ADD on the Kubernetes Cluster card.

A list of deployment target types with the Kubernetes cluster selected.

Display name

  1. Enter k8s-demo in the Display Name field.


  1. Select Development, Staging, and Production from the dropdown list.

Target tags

  1. Type in the same target tag you provided while configuring the Deploy Kubernetes YAML step, for example k8s.

The target tag won’t be available to select from the dropdown list yet, because it gets created during this step.

User interface for setting up a Kubernetes Cluster deployment target.


Octopus provides multiple methods for authenticating your Kubernetes cluster depending on your setup, including:

ServiceOctopus Authentication MethodNotes
AKSAzure Service PrincipalThe Azure Service Principal is only used with AKS clusters. To log into ACS or ACS-Engine clusters, you must use standard Kubernetes credentials like certificates or service account tokens.

Learn more in the Azure docs.
GKEGoogle Cloud AccountWhen using a GKE cluster, Google Cloud accounts let you authenticate using a Google Cloud IAM service account.

Learn more in the GKE docs.
EKSAWS AccountWhen using an EKS cluster, AWS accounts let you use IAM accounts and roles.

Learn more in the AWS docs.
Username and password
Client certificate
Learn more in the Kubernetes cluster docs.

Here are brief instructions on how to configure your cluster authentication in Octopus, since it will depend on your specific situation:

  1. Select the appropriate authentication method from the list.

Authentication methods for a Kubernetes Cluster deployment with various account options.

  1. Add a new account with the authentication details needed to access your cluster (more detailed instructions are linked in the table above).

Create Account page with form in Octopus Deploy.

  1. Complete the target authentication configuration fields like cluster name, resource group, etc.

Kubernetes authentication details, including Azure Service Principal and cluster information.

Need more details on how to configure various authentication methods? Read the Kubernetes cluster docs.

Kubernetes namespace

  1. Specify the namespace for this deployment target, for example default.

Worker Pool

  1. Select Hosted Ubuntu as the default Worker Pool.

Health check container image

  1. Select Runs inside a container, on a Worker.
  2. Select Docker Hub as the container registry.
  3. Copy the Ubuntu-based image and paste it into the container image field.
  4. SAVE your deployment target.

Health check container image expander with the latest Ubuntu-based image.

Health check

Octopus runs health checks on deployment targets and Workers to ensure they’re available and running the latest version of Calamari.

This process may take a few minutes since it’s acquiring the Worker and it needs to download the Worker Tools image.

  1. After saving, navigate to Connectivity in the left sidebar menu.
  2. Click the CHECK HEALTH button.

Deployment target connectivity status page with unknown state.

You can create and deploy a release now that you have a healthy deployment target.

Logs indicating a healthy deployment target.

Release and deploy

Create release

A release is a snapshot of the deployment process and the associated assets (Git resources, variables, etc.) as they exist when the release is created.

  1. Navigate to Projects in the top navigation and select your First K8s deployment project.
  2. Click the CREATE RELEASE button.

Deployment overview page with no deployments.

You’ll see a summary of the Git resources you provided in the Deploy Kubernetes YAML step.

Release summary showing Git resources

  1. Click SAVE.

Execute deployment

When you created this project, you selected the default lifecycle (Development ➜ Staging ➜ Production). Lifecycles determine which environments the project can be deployed to, and the promotion rules between those environments.

  1. Click DEPLOY TO DEVELOPMENT to deploy to the development environment associated with your cluster.
  2. Review the preview summary and when you’re ready, click DEPLOY.

Your first deployment may take slightly longer because your Docker image won’t be cached yet.

  1. Navigate to the KUBERNETES OBJECT STATUS tab to see the live status of your Kubernetes objects as the deployment progresses.

Kubernetes Object Status dashboard showing a successful deployment.

You’ve successfully completed your first deployment to Kubernetes! 🎉

As you continue to explore Octopus Deploy, consider diving deeper into powerful features like variables, joining our Slack community, or checking out our other tutorials to expand your knowledge.

More Kubernetes resources

Help us continuously improve

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

Send feedback

Page updated on Thursday, April 18, 2024