diff --git a/src/pages/docs/deployments/patterns/rollbacks/kubernetes/index.mdx b/src/pages/docs/deployments/patterns/rollbacks/kubernetes/index.mdx index b6ed44af73..f18f378888 100644 --- a/src/pages/docs/deployments/patterns/rollbacks/kubernetes/index.mdx +++ b/src/pages/docs/deployments/patterns/rollbacks/kubernetes/index.mdx @@ -1,201 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2023-10-04 -title: Rollback Kubernetes deployment -description: A guide on how to rollback a Kubernetes deployment -navOrder: 5 -hideInThisSectionHeader: true +layout: src/layouts/Redirect.astro +title: Redirect +redirect: /docs/kubernetes/tutorials/kubernetes-rollbacks +pubDate: 2024-07-29 +navSearch: false +navSitemap: false +navMenu: false --- -import ZeroConfigRollback from 'src/shared-content/rollbacks/zero-configuration-rollback.include.md'; -import CalculateDeploymentMode from 'src/shared-content/rollbacks/calculate-deployment-mode.include.md'; -import PreventReleaseProgression from 'src/shared-content/rollbacks/prevent-release-progression.include.md'; - -This guide will walk through rolling back a Kubernetes Deployment. The example application used in this guide is a containerized version of [PetClinic](https://bitbucket.org/octopussamples/petclinic/src/master/) that will create the following pods: - -- MySQL database container for the backend (deployment) -- Flyway database migrations container (job) -- PetClinic web frontend container (deployment) - -Database rollbacks are out of scope for this guide; refer to this [article](https://octopus.com/blog/database-rollbacks-pitfalls), which discusses methods of database rollbacks and when they are appropriate. - -## Existing deployment process - -For this guide, we'll start with an existing deployment process for deploying PetClinic to a Kubernetes cluster: - -1. Deploy MySQL Container -1. Deploy PetClinic web -1. Run Flyway job -1. Verify the deployment -1. Notify stakeholders - -:::figure -![](/docs/deployments/patterns/rollbacks/kubernetes/octopus-original-deployment-process.png) -::: - -:::div{.success} -View that deployment process on [samples instance](https://samples.octopus.app/app#/Spaces-762/projects/01-kubernetes-original/deployments/process). Please login as a guest. -::: - -## Zero-configuration Rollback - - - -## Simple rollback process - -The most common reason for a rollback is something is wrong with the release. In these cases, you'll want to block the bad release from [moving forward](/docs/releases/prevent-release-progression). - -The updated deployment process for a simple rollback would look like this: - -1. Calculate Deployment Mode -1. Deploy MySQL Container (skip during rollback) -1. Deploy PetClinic web -1. Run Flyway job (skip during rollback) -1. Verify the deployment -1. Notify stakeholders -1. Block Release Progression (only during rollback) - -:::figure -![](/docs/deployments/patterns/rollbacks/kubernetes/octopus-simple-rollback-process.png) -::: - -:::div{.success} -View that deployment process on [samples instance](https://samples.octopus.app/app#/Spaces-762/projects/02-kubernetes-simple-rollback/deployments/process). Please login as a guest. -::: - -### Calculate deployment mode - - - -### Skipping database steps - -Deploying the MySQL container and running the Flyway job should be skipped in a rollback scenario. For this guide, we're going to assume that the deployment of the MySQL container wasn't the cause for the rollback. As previously stated, database rollbacks are out of scope for this guide, so we'll skip the Flyway Job container as well. - -To ensure that both of those steps are not run during a rollback, use the following output variable from the `Calculate Deployment Mode` step as the Variable Run condition. - -``` -#{Octopus.Action[Calculate Deployment Mode].Output.RunOnDeploy} -``` - -:::div{.hint} -When viewing the deployment process at a glance, it is not readily apparent that a step has a run condition associated with it. Octopus Deploy provides a `Notes` field for each step where you can add information such as in which conditions the step will run as a way of self-documentation. -::: - -### Block release Progression - - - -## Complex rollback process - -A feature of Kubernetes is the revision history of the cluster components. The command `kubectl rollout history deployment.v1.apps/` lists all deployment revisions. - -``` -REVISION CHANGE-CAUSE -1 -2 -3 -``` - -Using this feature, we can create a rollback process that would allow us to roll back quickly. - -The new deployment process would look like this: - -1. Calculate Deployment Mode -1. Rollback Reason (only during rollback) -1. Deploy MySQL Container (skip during rollback) -1. Deploy PetClinic web -1. Run Flyway job (skip during rollback) -1. Verify the deployment -1. Notify stakeholders -1. Rollback to the previous version for PetClinic Web (only during rollback) -1. Block Release Progression (only during rollback) - -:::figure -![](/docs/deployments/patterns/rollbacks/kubernetes/octopus-complex-rollback-process.png) -::: - -:::div{.success} -View that deployment process on [samples instance](https://samples.octopus.app/app#/Spaces-762/projects/03-kubernetes-complex-rollback/deployments/process). Please login as a guest. -::: - -Next, we'll go through the newly added and altered steps: - -### Rollback reason - -This is a [Manual Intervention](/docs/projects/built-in-step-templates/manual-intervention-and-approvals) step that prompts the user for the reason they are rolling back. The text entered is stored in an output variable which will be used in the Block Release Progression step further down the process. - -### Deploy PetClinic Web - -The revision history command for Kubernetes showed that there were multiple revisions stored within Kubernetes for deployment. However, it's not obvious as to which revision belongs to which Octopus release. Adding a `kubernetes.io/change-cause` annotation to the `Deploy PetClinic Web` step would add the Octopus Release Number as the `change-cause` so we could later parse it for which revision to roll back to. - -:::figure -![](/docs/deployments/patterns/rollbacks/kubernetes/octopus-k8s-deployment-annotation.png) -::: - -Running `kubectl rollout history deployment.v1.apps/` would now show something like this. - -``` -REVISION CHANGE-CAUSE -1 2021.09.23.0 -2 2021.09.23.1 -3 2021.09.23.2 -``` - -### Rollback to the previous version for Petclinic Web - -Using the annotation from the `Deploy PetClinic Web`, we can use the following script to identify the revision we want to roll back to and perform the rollback using the built-in functionality of Kubernetes. This step uses the `Run a Kubectl CLI Script` step with the following code. - -```powershell -# Init variables -$k8sRollbackVersion = 0 -$rollbackVersion = $OctopusParameters['Octopus.Release.Number'] -$namespace = $OctopusParameters['Project.Namespace.Name'] -$deploymentName = $OctopusParameters['Project.Petclinic.Deployment.Name'] - -# Get revision history -Write-Host "Getting deployment $deploymentName revision history ..." -$revisionHistory = (kubectl rollout history deployment.v1.apps/$deploymentName -n $namespace) -$revisionHistory = $revisionHistory.Split("`n") - -# Loop through history starting at index 2 (the first couple of lines aren't versions) -Write-Host "Searching revision history for version $rollbackVersion ..." -for ($i = 2; $i -lt $revisionHistory.Count - 1; $i++) -{ - # Split it into two array elements - $revisionSplit = $revisionHistory[$i].Split(" ", [System.StringSplitOptions]::RemoveEmptyEntries) - - # Check version - if ($revisionSplit[1] -eq $rollbackVersion) - { - # Record version index - Write-Host "Version $rollbackVersion found!" - $k8sRollbackVersion = $revisionSplit[0] - - # Get out of for - break - } -} - -# Check to see if something was found -if ($k8sRollbackVersion -gt 0) -{ - # Issue rollback - Write-Host "Rolling Kubernetes deployment $deploymentName to revision $k8sRollbackVersion ..." - kubectl rollout undo deployment.v1.apps/$deploymentName -n $namespace --to-revision=$k8sRollbackVersion -} -else -{ - Write-Error "Version $rollbackVersion not found in the cluster revision history." -} -``` -### Block release progression - -The `Rollback Reason` step captures the reason for the rollback. We can pass the text entered in this step to the `Reason` field of this step by using the following output variable. - -``` -#{Octopus.Action[Rollback reason].Output.Manual.Notes} -``` - -## Choosing a rollback strategy - -It is our recommendation that you start with the simple rollback strategy, moving to the complex if you determine that the simple method doesn't suit your needs. \ No newline at end of file diff --git a/src/pages/docs/getting-started/first-kubernetes-deployment.md b/src/pages/docs/getting-started/first-kubernetes-deployment.md index b369b1b08d..567203a118 100644 --- a/src/pages/docs/getting-started/first-kubernetes-deployment.md +++ b/src/pages/docs/getting-started/first-kubernetes-deployment.md @@ -1,424 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2023-10-26 -modDate: 2024-06-27 -title: First Kubernetes deployment -description: This guide will walk you through how to configure your first deployment to Kubernetes in Octopus Deploy. -navOrder: 10 +layout: src/layouts/Redirect.astro +title: Redirect +redirect: /docs/kubernetes/tutorials/first-kubernetes-deployment +pubDate: 2024-07-29 +navSearch: false +navSitemap: false +navMenu: false --- - -👋 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: - -* [Octopus Cloud instance](https://octopus.com/start) -* Kubernetes cluster -* [Docker Hub account](https://hub.docker.com/) -* [GitHub account](https://github.com/) - -#### 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](https://github.com/OctopusSamples/OctoPetShop.git)** repository. - -:::figure -![Sample OctoPetShop GitHub repository](/docs/getting-started/first-kubernetes-deployment/octopetshop-repo.png) -::: - -2. In the top-right corner of the page, click **FORK**. -3. Provide an **Owner and repository name**, for example `OctoPetShop`. -4. Keep the **Copy the master branch only** checkbox selected. -5. Click **CREATE FORK**. -6. 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**. - -:::figure -![Get started welcome screen](/docs/getting-started/first-kubernetes-deployment/get-started.png) -::: - -## Add project - -Projects let you manage software applications and services, each with its deployment process. - -2. Give your project a descriptive name and click **SAVE**. - -:::figure -![Octopus Deploy 'Add New Project' form with fields for project details.](/docs/getting-started/first-kubernetes-deployment/new-project.png) -::: - -## 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. - -3. Select the environments you’d like to create and click **SAVE**. - -:::figure -![Environment selection options and deployment lifecycle visuals](/docs/getting-started/first-kubernetes-deployment/select-environments.png) -::: - -## 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. - -4. Click **SUBMIT**, and you'll be taken to your project. - -:::figure -![Octopus Deploy interface displaying a questionnaire](/docs/getting-started/first-kubernetes-deployment/survey.png) -::: - -## 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. - -:::figure -![Deployment process page with a button to create the process.](/docs/getting-started/first-kubernetes-deployment/create-process.png) -::: - -### Configure Deploy Kubernetes YAML step - -2. Select the **Kubernetes** filter and then add the **Deploy Kubernetes YAML** step. - -:::figure -![Kubernetes steps in the Octopus Deploy process editor.](/docs/getting-started/first-kubernetes-deployment/kubernetes-step.png) -::: - -#### 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. - -3. Select **Runs on a worker from a specific pool**. -4. Select **Hosted Ubuntu** from the dropdown menu. - -:::figure -![Worker Pool expander with 'Hosted Ubuntu' selected.](/docs/getting-started/first-kubernetes-deployment/worker-pool.png) -::: - -#### Target tags \{#on-behalf-of} -[Target tags](/docs/infrastructure/deployment-targets/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. - -5. Add a new target tag by typing it into the field. For this example, we'll use `k8s`. - -:::figure -![Target tag selection expander with 'k8s' tag currently added.](/docs/getting-started/first-kubernetes-deployment/on-behalf-of.png) -::: - -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. - -6. Select **Runs inside a container, on a worker**. - -:::figure -![Container image expander with 'Runs inside a container, on a worker selected'.](/docs/getting-started/first-kubernetes-deployment/container-image.png) -::: - -### 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). -1. Click the **ADD FEED** button and select **Docker Container Registry** from the **Feed Type** dropdown. - -:::figure -![Library section in Octopus with options to add external feeds.](/docs/getting-started/first-kubernetes-deployment/external-feeds.png) -::: - -1. Provide a name for your feed, for example `Docker Hub`. -1. Enter the feed URL to the public Docker Hub registry, for example `https://index.docker.io`. -1. You can leave the registry path blank for this example. - -:::figure -![Form to create a Docker container registry external feed.](/docs/getting-started/first-kubernetes-deployment/create-docker-feed.png) -::: - -1. Provide your credentials for Docker Hub. -1. Click **SAVE AND TEST**, and then type `nginx` into the package name field to test your external feed. - -:::figure -![A search interface in Octopus to test the Docker Hub repository.](/docs/getting-started/first-kubernetes-deployment/test-docker-feed.png) -::: - -Close the window and return to configuring the **Deploy Kubernetes YAML** step. - -#### Container image -7. Click **REFRESH** and select **Docker Hub** as your Container Registry. -1. Copy the latest **Ubuntu-based image** from the help text and paste it into the container image field. - -:::figure -![Container image expander using the latest Ubuntu-based image.](/docs/getting-started/first-kubernetes-deployment/container-image-docker.png) -::: - -#### 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. - -9. Select **Git Repository** as your YAML source. - -:::figure -![YAML source expander with Git repository selected](/docs/getting-started/first-kubernetes-deployment/git-repository.png) -::: - -#### Git repository details -10. Select **Library** and add a new Git credential by clicking the **+** icon. -1. Click the **ADD GIT CREDENTIAL** button. -1. Enter a name for your Git credential. -1. Provide your GitHub username. - -:::figure -![A section in the library interface that lets users create and manage Git credentials.](/docs/getting-started/first-kubernetes-deployment/git-credential.png) -::: - -### Generate GitHub personal access token -Github.com 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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - -1. Navigate to [github.com](https://github.com) and log in to your account. -1. Click your profile picture in the top right corner. -1. Click **SETTINGS**. -1. Scroll down to the bottom of the page and click **DEVELOPER SETTINGS**. -1. Under **Personal access tokens**, click **FINE-GRAINED TOKENS**. -1. Click **GENERATE NEW TOKEN**. -1. Under **Token name**, enter a name for the token. -1. Under **Expiration**, provide an expiration for the token. -1. Select a Resource Owner. -1. Under **Repository Access**, choose **Only select repositories** and select the **OctoPetShop** repository from the dropdown. -1. Click **REPOSITORY PERMISSIONS**, scroll down to **Contents** and select **Read-only**. -1. Scroll down to the **Overview**, and you should have 2 permissions for one of your repositories (contents and metadata). -1. Click **Generate token** and copy the token. - -:::figure -![A GitHub settings page where users can manage permissions for fine-grained tokens.](/docs/getting-started/first-kubernetes-deployment/generate-token.png) -::: - -#### Git repository details -14. Paste the token into Octopus's personal access token field. -1. **Save** your Git credential and return to the **Deploy Kubernetes YAML** step. -1. Click the refresh icon next to the **Select Git credential** dropdown. -1. Select the Git credential you created earlier. - -:::figure -![Authentication expander with a Git repository selected from the library.](/docs/getting-started/first-kubernetes-deployment/completed-git-credential.png) -::: - -#### Repository URL -18. Enter the full URL to the Git repository where you store the YAML files you want to deploy, for example `https://github.com/your-user/OctoPetShop.git`. - -:::figure -![Repository URL expander where the user's YAML files are stored.](/docs/getting-started/first-kubernetes-deployment/repository-url.png) -::: - -#### Branch settings -19. Provide the default branch you want to use, for example **master** if you’re using the sample repo. - -#### Paths -20. 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`. - -:::figure -![The Paths expander that lets users specify the paths to their YAML files using glob patterns.](/docs/getting-started/first-kubernetes-deployment/paths.png) -::: - -#### Kubernetes object status check -This feature gives you live status updates during deployment for all the Kubernetes objects you're deploying. - -21. Keep the default **Check that Kubernetes objects are running successfully** option selected with the default timeout of **180** seconds. - -:::figure -![Kubernetes object status check expander with the default option and timeout selected.](/docs/getting-started/first-kubernetes-deployment/k8s-object-status-check.png) -::: - -#### Structured configuration variables -This is an advanced feature that you can skip for this tutorial. Learn more about [structured configuration variables in our docs](https://octopus.com/docs/projects/steps/configuration-features/structured-configuration-variables-feature). - -#### Referenced packages -This is an advanced feature that you can skip for this tutorial. Learn more about [references packages in our docs](https://octopus.com/docs/deployments/custom-scripts/run-a-script-step#referencing-packages). - -#### Namespace -22. 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. - -#### Conditions -You can set [conditions](https://octopus.com/docs/projects/steps/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 **Infrastructure** ➜ **Deployment Targets**, and click **ADD DEPLOYMENT TARGET**. - -:::figure -![Deployment targets page with no targets added.](/docs/getting-started/first-kubernetes-deployment/deployment-targets.png) -::: - -2. Select **KUBERNETES CLUSTER** and click **ADD** on the Kubernetes Cluster card. - -:::figure -![A list of deployment target types with the Kubernetes cluster selected.](/docs/getting-started/first-kubernetes-deployment/add-k8s-target.png) -::: - -#### Display name -3. Enter `k8s-demo` in the **Display Name** field. - -#### Environments -4. Select **Development**, **Staging**, and **Production** from the dropdown list. - -#### Target tags \{#target-roles} -5. Type in the same [target tag](/docs/infrastructure/deployment-targets/target-tags) 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. - -:::figure -![User interface for setting up a Kubernetes Cluster deployment target.](/docs/getting-started/first-kubernetes-deployment/create-k8s-cluster.png) -::: - -#### Authentication -Octopus provides multiple methods for authenticating your Kubernetes cluster depending on your setup, including: - -| **Service** | **Octopus Authentication Method** | **Notes** | -|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| AKS | [Azure Service Principal](https://octopus.com/docs/infrastructure/accounts/azure) | The 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](https://learn.microsoft.com/en-us/azure/aks/operator-best-practices-identity). | -| GKE | [Google Cloud Account](https://octopus.com/docs/infrastructure/accounts/google-cloud) | When using a GKE cluster, Google Cloud accounts let you authenticate using a Google Cloud IAM service account.

Learn more in the [GKE docs](https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication). | -| EKS | [AWS Account](https://octopus.com/docs/infrastructure/accounts/aws) | When using an EKS cluster, AWS accounts let you use IAM accounts and roles.

Learn more in the [AWS docs](https://docs.aws.amazon.com/eks/latest/userguide/cluster-auth.html). | -| Other | [Tokens](https://octopus.com/docs/infrastructure/accounts/tokens)
[Username and password](https://octopus.com/docs/infrastructure/accounts/username-and-password)
[Client certificate](https://octopus.com/docs/infrastructure/deployment-targets/kubernetes/kubernetes-api#add-a-kubernetes-target) | Learn more in the [Kubernetes cluster docs](https://octopus.com/docs/infrastructure/deployment-targets/kubernetes/kubernetes-api#add-a-kubernetes-target). | - - -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. - -:::figure -![Authentication methods for a Kubernetes Cluster deployment with various account options.](/docs/getting-started/first-kubernetes-deployment/target-authentication-methods.png) -::: - -2. Add a new account with the authentication details needed to access your cluster (more detailed instructions are linked in the table above). - -:::figure -![Create Account page with form in Octopus Deploy.](/docs/getting-started/first-kubernetes-deployment/create-account.png) -::: - -3. Complete the target authentication configuration fields like cluster name, resource group, etc. - -:::figure -![Kubernetes authentication details, including Azure Service Principal and cluster information.](/docs/getting-started/first-kubernetes-deployment/target-authentication.png) -::: - -Need more details on how to configure various authentication methods? Read the [Kubernetes cluster docs](https://octopus.com/docs/infrastructure/deployment-targets/kubernetes/kubernetes-api#add-a-kubernetes-target). - -#### Kubernetes namespace -6. Specify the namespace for this deployment target, for example `default`. - -#### Worker Pool -7. Select **Hosted Ubuntu** as the default Worker Pool. - -#### Health check container image -8. Select **Runs inside a container, on a Worker**. -1. Select **Docker Hub** as the container registry. -1. Copy the **Ubuntu-based image** and paste it into the container image field. -1. **SAVE** your deployment target. - -:::figure -![Health check container image expander with the latest Ubuntu-based image.](/docs/getting-started/first-kubernetes-deployment/health-check-container-image.png) -::: - -#### 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. -1. Click the **CHECK HEALTH** button. - -:::figure -![Deployment target connectivity status page with unknown state.](/docs/getting-started/first-kubernetes-deployment/health-check-connectivity.png) -::: - -You can create and deploy a release now that you have a healthy deployment target. - -:::figure -![Logs indicating a healthy deployment target.](/docs/getting-started/first-kubernetes-deployment/healthy-target.png) -::: - -## 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. -1. Click the **CREATE RELEASE** button. - -:::figure -![Deployment overview page with no deployments.](/docs/getting-started/first-kubernetes-deployment/deployment-overview.png) -::: - -You’ll see a summary of the Git resources you provided in the **Deploy Kubernetes YAML** step. - -:::figure -![Release summary showing Git resources](/docs/getting-started/first-kubernetes-deployment/release-summary.png) -::: - -3. 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. -1. 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. - -3. Navigate to the **KUBERNETES OBJECT STATUS** tab to see the live status of your Kubernetes objects as the deployment progresses. - -:::figure -![Kubernetes Object Status dashboard showing a successful deployment.](/docs/getting-started/first-kubernetes-deployment/deployment-success.png) -::: - -You’ve successfully completed your first deployment to Kubernetes! 🎉 - -As you continue to explore Octopus Deploy, consider diving deeper into powerful features like [variables](https://octopus.com/docs/projects/variables), joining our [Slack community](http://octopususergroup.slack.com), or checking out our other tutorials to expand your knowledge. - -## More Kubernetes resources - -* [Deploy with the Kustomize step](https://octopus.com/docs/deployments/kubernetes/kustomize) -* [Deploy a Helm chart](https://octopus.com/docs/deployments/kubernetes/helm-update) -* [Using variables for Kubernetes without breaking YAML](https://octopus.com/blog/structured-variables-raw-kubernetes-yaml) diff --git a/src/pages/docs/kubernetes/index.md b/src/pages/docs/kubernetes/index.md index f1a1ec6f0d..c72ccee7dc 100644 --- a/src/pages/docs/kubernetes/index.md +++ b/src/pages/docs/kubernetes/index.md @@ -1,14 +1,11 @@ --- layout: src/layouts/Default.astro -pubDate: 2024-01-01 -modDate: 2024-01-01 +pubDate: 2023-01-01 +modDate: 2024-03-26 title: Kubernetes -navTitle: Overview -navSection: Kubernetes description: Octopus Deploy provides support for deploying Kubernetes resources. navOrder: 25 --- - import RecentlyUpdated from '@components/RecentlyUpdated.astro'; import Card from 'src/components/Card.astro'; @@ -73,7 +70,7 @@ When you’re ready to apply Octopus to a real scenario, we recommend that you: ## Deployments at scale Learn more about deploying to multiple apps with Octopus, with these guides: -- Release triggers [link] and [channels](https://octopus.com/docs/releases/channels) to automate deployments +- [Release triggers](https://octopus.com/docs/projects/project-triggers/external-feed-triggers) and [channels](https://octopus.com/docs/releases/channels) to automate deployments - [Step templates](https://octopus.com/docs/projects/custom-step-templates) to create new pipelines with ease - [Configuration as Code](https://octopus.com/docs/projects/version-control) to manage deployment pipeline versions - [Users, roles, and teams](https://octopus.com/docs/getting-started/best-practices/users-roles-and-teams) diff --git a/src/pages/docs/kubernetes/steps/helm.md b/src/pages/docs/kubernetes/steps/helm.md index 42a7f6b4eb..c488f98b1f 100644 --- a/src/pages/docs/kubernetes/steps/helm.md +++ b/src/pages/docs/kubernetes/steps/helm.md @@ -2,10 +2,9 @@ layout: src/layouts/Default.astro pubDate: 2023-01-01 modDate: 2024-04-23 -title: Deploy a Helm Chart -description: Deploy a Helm chart to a Kubernetes cluster +title: Deploy a Helm chart +description: Deploy a Helm chart to a Kubernetes cluster. navOrder: 30 -hideInThisSectionHeader: false --- :::div{.hint} @@ -17,11 +16,13 @@ Helm Charts are like a package manager for Kubernetes applications, allowing use ## Helm chart sources You can source your Helm charts from two different sources: + - Packages from Helm or OCI feeds - Git Repository ### Helm feed -A Helm Feed in Octopus refers to a [Helm Chart repository](https://helm.sh/docs/topics/chart_repository/). This repository is effectively just an HTTP server that houses an `index.yaml` which describes the charts available on that server. Octopus uses this index file to determine the available "packages" (Charts) and versions. A chart is a tarball that looks like `alpine-0.1.2.tgz` which for this example Octopus will interpret as having PackageID `alpine` and version `0.1.2`. There are various ways you can host a chart repository, including third-party tools like [ChartMuseum](https://github.com/chartmuseum/chartmuseum), [Artifactory](https://www.jfrog.com/confluence/display/JFROG/Kubernetes+Helm+Chart+Repositories), [Cloudsmith](https://help.cloudsmith.io/docs/helm-chart-repository), or even hosting your own [static web server](https://helm.sh/docs/topics/chart_repository/#hosting-chart-repositories). + +A Helm Feed in Octopus refers to a [Helm Chart repository](https://helm.sh/docs/topics/chart_repository/). This repository is effectively just an HTTP server that houses an `index.yaml` which describes the charts available on that server. Octopus uses this index file to determine the available "packages" (Charts) and versions. A chart is a tarball that looks like `alpine-0.1.2.tgz` which for this example Octopus will interpret as having PackageID `alpine` and version `0.1.2`. There are various ways you can host a chart repository, including third-party tools like [ChartMuseum](https://github.com/chartmuseum/chartmuseum), [Artifactory](https://jfrog.com/help/r/jfrog-artifactory-documentation/kubernetes-helm-chart-repositories), [Cloudsmith](https://help.cloudsmith.io/docs/helm-chart-repository), or even hosting your own [static web server](https://helm.sh/docs/topics/chart_repository/#hosting-chart-repositories). :::figure ![Helm Feed](/docs/deployments/kubernetes/helm-update/helm-feed.png) @@ -29,7 +30,7 @@ A Helm Feed in Octopus refers to a [Helm Chart repository](https://helm.sh/docs/ :::div{.info} -The built-in repository is [capable of storing Helm Charts](/docs/packaging-applications/#supported-formats). However, the mechanism for determining the **PackageID** and **Version** may differ depending on the contents of the `.tgz` file. If the `.tgz` file contains a `chart.yaml` file, the PackageID is determined by the `name`, and the version is determined by the `version` sections of the YAML. +The built-in repository is [capable of storing Helm Charts](/docs/packaging-applications/#supported-formats). However, the mechanism for determining the **PackageID** and **Version** may differ depending on the contents of the `.tgz` file. If the `.tgz` file contains a `chart.yaml` file, the PackageID is determined by the `name`, and the version is determined by the `version` sections of the YAML. ```yaml apiVersion: v2 @@ -74,11 +75,12 @@ You can find more information about this feature in this [blog post on using Git Sourcing your Helm charts from a Git Repository can streamline your deployment process by reducing the amount of steps required to get them into Octopus. -To configure a Git Repository source, select the `Git Repository` option as your Chart Source. +To configure a Git Repository source, select the `Git Repository` option as your Chart Source. #### Database projects If you are storing your project configuration directly in Octopus (i.e. not in a Git repository using the [Configuration as code feature](/docs/projects/version-control)), you can source your charts from a Git repository by entering the details of the repository, including: + - URL - Credentials (either anonymous or selecting a Git credential from the Library) @@ -89,6 +91,7 @@ When creating a Release, you choose the tip of a branch for your Helm charts. Th If you are storing your project configuration in a Git repository using the [Configuration as code feature](/docs/projects/version-control), in addition to the option above, you can source your charts from the same Git repository as your deployment process by selecting **Project** as the Git repository source. When creating a Release using this option, the commit hash used for your deployment process will also be used to source the chart files. ## Helm upgrade step + Since the [helm upgrade](https://docs.helm.sh/helm/#helm-upgrade) command provides the ability to ensure that the chart is installed when it runs for the first time (by using the `--install` argument), this upgrade command is the most practical step to provide. :::div{.success} @@ -102,6 +105,7 @@ Remember that since the Kubernetes cluster connection context is available via t ::: #### Kubernetes release + The Kubernetes release uniquely identifies the released chart in the cluster. Because of the unique naming requirements of the release name, the default value provided includes both the project and environment name to ensure that successive Octopus releases do not conflict with one another. When redeploying new versions of the chart, this name is what is used to uniquely identify the resources that are related to that Octopus deployment. Helm requires that this name consist of only lowercase alpha numeric and dash (-) characters. :::div{.hint} @@ -109,9 +113,11 @@ Due to the design of Helm, the release names must be [unique across the entire c ::: #### Reset values + By default Helm will carry forward any existing configuration between deployments if not explicitly overridden. To ensure that the Octopus provided configuration acts as the source of truth, the `--reset-values` argument is set on the invoked command however this can be disabled if desired. #### Helm client tool + Helm performs some strict version checks when performing any commands against the cluster and requires that the client have the same minor version as the tiller service (the helm component running in your cluster) in your Kubernetes cluster. :::div{.success} @@ -129,13 +135,38 @@ Since it is quite common to have different versions of Helm across your deployme The configuration for the Kubernetes resources required in a Helm Chart can be provided by making use of [Chart Templates](https://docs.helm.sh/chart_template_guide/). In each of the following options, the values file are passed into the `helm upgrade` command with the `-f` argument. The template values are applied in the order that they are displayed (i.e. with values provided the `Explicit key values` option taking a higher precedence than the same value obtained via the `Raw values YAML` option). - **Explicit Key Values:** This option provides the ability to quickly provide key/value pairs of template configuration. -- **Raw values YAML:** Standard Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions) can be used so long as the final contents are a valid YAML file. +- **Raw values YAML:** Standard Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions) can be used so long as the final contents are a valid YAML file. - **Files in Chart Package:** If there are any other values files contained within the selected chart (by default, `./values.yaml` in the root of the package is picked up by helm), they can be referenced with this option. Octopus Variable replacement will be performed on the file before being used. - **Files in Additional Packages:** When using publicly available Helm Charts as the package source for this step, you may want to source your custom values files from outside Octopus, for example, through files committed to a [GitHub feed](/docs/packaging-applications/package-repositories/github-feeds). Files obtained through this option will have Octopus Variable replacement performed before being used. +## Separating image updates from Helm chart updates + +Application updates are often rolled up into full Helm chart version updates because that is the only mechanism provided. When deploying Helm charts with Octopus Deploy, a values file can be used for container image tags so that your Helm charts only get updated when your infrastructure definition changes. + +### Setting up referenced images with Helm chart deployments + +Using this [Helm hello-world chart](https://github.com/helm/examples/tree/main/charts/hello-world) as an example. + +For each of the container images referenced by the Helm chart, add a referenced image under **Docker image references**. The following snippet assumes the referenced package has the **Name** `nginx`. + +Edit the RAW Values YAML to update the image repository and tag. Take a look inside the example Helm chart to see how they've configured their template to use these values. + +```yaml +image: + repository: #{Octopus.Action.Package[nginx].PackageId} + tag: #{Octopus.Action.Package[nginx].PackageVersion} +``` + +### Automatically creating releases + +Using referenced images with your Helm chart step allow [external feed triggers](/docs/projects/project-triggers/external-feed-triggers) to automatically create releases when one or more new images are pushed to your registries. + +Further to this, [lifecycles](/docs/releases/lifecycles) can be used to fully automate deploying your releases to selected environments. + ## Known limitations + :::div{.warning} -Please note that [Cloud Dynamic Workers](/docs/infrastructure/workers/dynamic-worker-pools/#available-dynamic-worker-images) come with Helm 2.9.1 installed. This means that if you chose V3 on the Helm Step Template, it will fall back to V2 during execution. To get around this problem, use the [Execution Containers](/docs/projects/steps/execution-containers-for-workers) feature with the [worker tools image](https://hub.docker.com/r/octopusdeploy/worker-tools). +Please note that [Cloud Dynamic Workers](/docs/infrastructure/workers/dynamic-worker-pools/#available-dynamic-worker-images) come with Helm 2.9.1 installed. This means that if you chose V3 on the Helm Step Template, it will fall back to V2 during execution. To get around this problem, use the [Execution Containers](/docs/projects/steps/execution-containers-for-workers) feature with the [worker tools image](https://hub.docker.com/r/octopusdeploy/worker-tools). ::: Helm provides [provenance](https://helm.sh/docs/topics/provenance/) tools that assist in verifying the integrity and origin of a package. Octopus does not _currently automatically_ perform validation checks during a deployment using these tools however this may change in the future. @@ -147,9 +178,9 @@ See [https://github.com/OctopusDeploy/Issues/issues/8132](https://github.com/Oct ::: :::div{.warning} -Due to how deployment cancellation currently works, the Helm `--atomic` argument does not result in automatic rollbacks when a deployment is cancelled. +Due to how deployment cancellation currently works, the Helm `--atomic` argument does not result in automatic rollbacks when a deployment is cancelled. This means that any Helm chart changes that were being deployed may become stuck or only partially deployed, and require manual clean-up. -Furthermore, if the Octopus deployment timeout is set lower than the Helm timeout, a similar issue may arise if the Helm chart deployment is interrupted midway. +Furthermore, if the Octopus deployment timeout is set lower than the Helm timeout, a similar issue may arise if the Helm chart deployment is interrupted midway. To ensure a smooth deployment experience, we recommend setting a larger Octopus timeout than the Helm timeout. ::: diff --git a/src/pages/docs/kubernetes/steps/kubernetes-resources.md b/src/pages/docs/kubernetes/steps/kubernetes-resources.md index 6f05af4294..2451019f97 100644 --- a/src/pages/docs/kubernetes/steps/kubernetes-resources.md +++ b/src/pages/docs/kubernetes/steps/kubernetes-resources.md @@ -597,7 +597,7 @@ The [command and arguments](https://oc.to/KubernetesCommand) that are executed w This section has two fields: `Command` and `Command arguments`. Each plays a slightly different role relating to how Docker images define the command that is used to launch the container. -Docker images can define an [ENTRYPOINT](https://oc.to/DockerEntrypoint), a [CMD](https://oc.to/Docker/), or both. +Docker images can define an [ENTRYPOINT](https://oc.to/DockerEntrypoint), a [CMD](https://docs.docker.com/reference/dockerfile/#cmd), or both. When both are defined, the CMD value is passed to the ENTRYPOINT. So if CMD is set to `["hello", "world"]` and ENTRYPOINT is set to `["print"]`, the resulting command would be `print hello world`. @@ -677,7 +677,7 @@ The [command and arguments](https://oc.to/KubernetesCommand) that are executed w This section has two fields: `Command` and `Command arguments`. Each plays a slightly different role relating to how Docker images define the command that is used to launch the container. -Docker images can define an [ENTRYPOINT](https://oc.to/DockerEntrypoint), a [CMD](https://oc.to/Docker/), or both. +Docker images can define an [ENTRYPOINT](https://oc.to/DockerEntrypoint), a [CMD](https://docs.docker.com/reference/dockerfile/#cmd), or both. When both are defined, the CMD value is passed to the ENTRYPOINT. So if CMD is set to `["hello", "world"]` and ENTRYPOINT is set to `["print"]`, the resulting command would be `print hello world`. diff --git a/src/pages/docs/kubernetes/steps/kustomize.mdx b/src/pages/docs/kubernetes/steps/kustomize.mdx index e9670d437f..a5a7a2d54d 100644 --- a/src/pages/docs/kubernetes/steps/kustomize.mdx +++ b/src/pages/docs/kubernetes/steps/kustomize.mdx @@ -63,7 +63,7 @@ Also, remember that in Linux workers, the paths are case-sensitive, so it is alw ## Substitute Variables in Files -This setting is useful, for example, when you want to put your application specific configuration settings in a `.env` file and also have the value scoped per environment and/or tenant, see more information regarding [variable scoping](/docs/projects/variables#scoping-variables). +This setting is useful, for example, when you want to put your application specific configuration settings in a `.env` file and also have the value scoped per environment and/or tenant, see more information regarding [variable scoping](/docs/projects/variables/getting-started/#scoping-variables). The target file paths are relative to the root of the git repository. Again remember that in Linux workers, paths are case-sensitive, so it is always good practice to check this. You can use glob patterns to target multiple files. [Learn more about glob patterns](/docs/deployments/kubernetes/glob-patterns). diff --git a/src/pages/docs/kubernetes/steps/yaml.md b/src/pages/docs/kubernetes/steps/yaml.md index 9f55a596b8..f402deb7d7 100644 --- a/src/pages/docs/kubernetes/steps/yaml.md +++ b/src/pages/docs/kubernetes/steps/yaml.md @@ -1,11 +1,10 @@ --- layout: src/layouts/Default.astro pubDate: 2023-07-28 -modDate: 2024-07-29 +modDate: 2024-04-23 title: Deploy Kubernetes YAML -description: Deploy Kubernetes YAML +description: Deploy Kubernetes YAML. navOrder: 20 -hideInThisSectionHeader: true --- :::div{.hint} @@ -14,17 +13,18 @@ hideInThisSectionHeader: true Octopus supports the deployment of Kubernetes resources through the `Deploy Kubernetes YAML` step. -This step lets you configure Kubernetes manually, leveraging the full power of Octopus features to support your setup. +This step lets you configure Kubernetes manually, leveraging the full power of Octopus features to support your setup. This approach is more flexible and gives you complete control over the YAML but requires deeper knowledge of Kubernetes configuration. -# YAML Sources +## YAML Sources You can source your YAML from three different sources: + - Git Repository - Package - Inline Script -## Git Repository +### Git Repository :::div{.hint} Sourcing from Git Repositories was added in Octopus **2023.3**. @@ -50,14 +50,15 @@ To configure a Git Repository source, select the `Git Repository` option as your :::figure ![Deploy Kubernetes YAML with a Git Manifest](/docs/deployments/kubernetes/deploy-raw-yaml/git-repository.png) ::: - + :::div{.hint} -When you choose the tip of a branch for your Git Manifest when creating a Release, the commit hash is saved to the Release. +When you choose the tip of a branch for your Git Manifest when creating a Release, the commit hash is saved to the Release. This means redeploying that release will only ever use that specific commit and not the _new_ tip of the branch. ::: -## Package -Sourcing from a Package is the traditional way to load data from external sources. +### Package + +Sourcing from a Package is the traditional way to load data from external sources. You can specify the Package Feed and Package ID as well as a path or paths† to the file(s) in the package that you want to deploy. To configure a package source, select the `Package` option as your YAML Source. @@ -68,9 +69,9 @@ To configure a package source, select the `Package` option as your YAML Source. †In 2023.3, sourcing from packages can take advantage of [Glob Patterns and Multiple Paths](/docs/deployments/kubernetes/deploy-raw-yaml#glob-patterns-and-multiple-paths). -## Inline YAML +### Inline YAML -The simplest way to get going with this step is to use Inline YAML. +The simplest way to get going with this step is to use Inline YAML. You can create your YAML resources in the inline editor which will be saved in the project in Octopus. To configure an inline YAML source, select the `Inline YAML` as your YAML Source, click `Add Source Code` and start writing! @@ -83,31 +84,45 @@ To configure an inline YAML source, select the `Inline YAML` as your YAML Source This is **not** the recommended approach for advanced cases as it does not allow for version management unless you are using it in conjunction with [Config As Code](/docs/projects/version-control). ::: +## Referencing packages + +Container images can be selected as **[Referenced Packages](/docs/deployments/custom-scripts/run-a-script-step#referencing-packages)** to automatically generate variables referring to the image name and tag that can be substituted in your manifests. + +For a package with the name `nginx`, you can substitute the image repository with `#{Octopus.Action.Package[nginx].PackageId}` and the tag with `#{Octopus.Action.Package[nginx].PackageVersion}`. The tag is selected when creating the release, allowing you to create new releases without any changes to your YAML manifests. + +### Automatically creating releases + +Using referenced images with your deploy YAML step allow [external feed triggers](/docs/projects/project-triggers/external-feed-triggers) to automatically create releases when one or more new images are pushed to your registries. + +Further to this, [lifecycles](/docs/releases/lifecycles) can be used to fully automate deploying your releases to selected environments. + ## Glob Patterns and Multiple Paths {#glob-patterns-and-multiple-paths} -The Git Repository and Package data sources require you to specify which files you would like to apply from the git repo or package. -Previously we only allowed a single file to be applied via an explicit path. +The Git Repository and Package data sources require you to specify which files you would like to apply from the git repo or package. +Previously we only allowed a single file to be applied via an explicit path. In release 2023.3, we have added the ability to source multiple files via multiple paths for both Git Repositories and Packages. There are a few different ways to take advantage of this feature: + 1. You can list several paths by separating them with a new line. - ``` + + ```text deployments/apply-first.yaml services/apply-second.yml ``` - - **Note:** *Each path will be applied in order from top to bottom.* + + **Note:** _Each path will be applied in order from top to bottom._ 2. You can use a glob pattern to select multiple files in a single path. - ``` + + ```text **/*.{yaml,yml} ``` - + **Note:** *All files matching a glob pattern will be applied at the same time.* 3. Both options at the same time. This gives you the best of both worlds! - **Note:** *If multiple glob patterns find the same file, the file will be applied twice.* - + **Note:** *If multiple glob patterns find the same file, the file will be applied twice.* [Learn more about glob patterns](/docs/deployments/kubernetes/glob-patterns). diff --git a/src/pages/docs/kubernetes/tutorials/first-kubernetes-deployment.md b/src/pages/docs/kubernetes/tutorials/first-kubernetes-deployment.md index 5630721670..b8d3f022b3 100644 --- a/src/pages/docs/kubernetes/tutorials/first-kubernetes-deployment.md +++ b/src/pages/docs/kubernetes/tutorials/first-kubernetes-deployment.md @@ -1,10 +1,10 @@ --- layout: src/layouts/Default.astro pubDate: 2023-10-26 -modDate: 2024-04-18 +modDate: 2024-06-27 title: First Kubernetes deployment description: This guide will walk you through how to configure your first deployment to Kubernetes in Octopus Deploy. -navOrder: 10 +navOrder: 20 --- 👋 Welcome to Octopus Deploy! @@ -116,7 +116,7 @@ Worker Pools are groups of Workers. When a task is assigned to a Worker, the tas ::: #### Target tags \{#on-behalf-of} -[Target tags](/docs/infrastructure/deployment-targets#target-roles) (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. +[Target tags](/docs/infrastructure/deployment-targets/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. 5. Add a new target tag by typing it into the field. For this example, we'll use `k8s`. @@ -304,7 +304,7 @@ Wherever you’re deploying your software, these machines and services are known 4. Select **Development**, **Staging**, and **Production** from the dropdown list. #### Target tags \{#target-roles} -5. Type in the same [target tag](/docs/infrastructure/deployment-targets#target-roles) you provided while configuring the **Deploy Kubernetes YAML** step, for example `k8s`. +5. Type in the same [target tag](/docs/infrastructure/deployment-targets/target-tags) 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.