-
Notifications
You must be signed in to change notification settings - Fork 91
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add external feed trigger examples #2250
Changes from 5 commits
6bd2d25
fc9fc9e
d0408d0
c42f801
a90d5f7
be9db7a
ccf9549
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,139 @@ | ||
--- | ||
layout: src/layouts/Default.astro | ||
pubDate: 2024-05-02 | ||
modDate: 2024-05-02 | ||
title: Automatically tracking third party helm charts | ||
description: External feed triggers allow you to automatically create a new release as a result of new container images or helm charts being pushed to their respective repositories. | ||
navOrder: 41 | ||
--- | ||
|
||
With a growing number of applications being provided with Helm charts as a primary method of installation, often all that needs to be done is a `helm install` against your cluster and the application will be up and running. | ||
|
||
However managing updates can be a more involved process. Not only do you need to know when a new release is available, but you also need to have someone with credentials to run the `helm upgrade` against your cluster. Meaning you'll either need to share important credentials among everyone performing updates or have only a few people busy performing these updates. | ||
|
||
Octopus Deploy provides a full workflow to manage updates, either hands on or fully hands off. | ||
|
||
### Setting up the project | ||
|
||
A Helm chart deployment like this is simple with Octopus Deploy. | ||
|
||
1. Start with the **Deploy a Helm chart** step | ||
2. Link it to the required Kubernetes clusters via target tags | ||
3. Reference the desired Helm chart | ||
4. Configure the namespace and any values required for your application | ||
|
||
:::figure | ||
![Helm chart deployment process](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-deployment-process.png) | ||
::: | ||
|
||
Sample OCL for version controlled projects: | ||
|
||
```ocl | ||
step "deploy-ingress-nginx-helm-chart" { | ||
name = "Deploy Ingress Nginx Helm Chart" | ||
properties = { | ||
Octopus.Action.TargetRoles = "kind" | ||
} | ||
|
||
action { | ||
action_type = "Octopus.HelmChartUpgrade" | ||
properties = { | ||
Octopus.Action.Helm.ClientVersion = "V3" | ||
Octopus.Action.Helm.Namespace = "nginx-local" | ||
Octopus.Action.Helm.ReleaseName = "ingress-nginx" | ||
Octopus.Action.Helm.ResetValues = "True" | ||
Octopus.Action.Package.DownloadOnTentacle = "False" | ||
Octopus.Action.Package.FeedId = "ingress-nginx" | ||
Octopus.Action.Package.PackageId = "ingress-nginx" | ||
} | ||
|
||
packages { | ||
acquisition_location = "Server" | ||
feed = "ingress-nginx" | ||
package_id = "ingress-nginx" | ||
properties = { | ||
SelectionMode = "immediate" | ||
} | ||
} | ||
} | ||
} | ||
``` | ||
|
||
### Helpful settings | ||
|
||
By default, Octopus will start versioning releases from `0.0.1` and count up patch versions from there. Helm charts already have a meaningful version number that you may wish to use instead. | ||
|
||
You can change our releases to track the Helm chart version by heading to the project settings and changing the release versioning rule to use the version number from our deployment step. | ||
|
||
:::figure | ||
![Change release versioning](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-versioning-rule.png) | ||
::: | ||
|
||
Sample OCL for version controlled projects: | ||
|
||
```ocl | ||
versioning_strategy { | ||
donor_package { | ||
step = "deploy-ingress-nginx-helm-chart" | ||
} | ||
} | ||
``` | ||
|
||
### Creating the trigger | ||
|
||
Triggers can be created directly from the deployment process by clicking the **Create a trigger** link, or by navigating to the **Triggers** page and clicking **Add Trigger**. | ||
|
||
Enter a name and a select which container images or Helm charts you'd like to watch for updates. | ||
In this example, the Default channel has a lifecycle that will automatically deploy to the Development environment for testing, more on that later. | ||
|
||
:::figure | ||
![Helm chart create trigger](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-create-trigger.png) | ||
::: | ||
|
||
Once the trigger is created, you can watch the triggers execution history. Within a couple of minutes you'll see your very first release created. | ||
|
||
:::figure | ||
![Helm chart trigger history](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-trigger-history.png) | ||
::: | ||
|
||
### Automatic deployment strategies | ||
|
||
Back on the project dashboard, you can see the release isn't only created but successfully deployed to your cluster as well. | ||
|
||
:::figure | ||
![Helm chart deployed release](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-deployed-release.png) | ||
::: | ||
|
||
But what if there was only a production environment? You may be a bit more careful with deploying updates the moment they are released. You can control this with channels and lifecycles. | ||
|
||
First [create a new lifecycle](/docs/releases/lifecycles), called Production here. | ||
|
||
:::figure | ||
![Helm chart production lifecycle](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-production-lifecycle.png) | ||
::: | ||
|
||
Then [create a channel](/docs/releases/channels) in the project that uses this lifecycle. | ||
|
||
:::figure | ||
![Helm chart production channel](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-production-channel.png) | ||
::: | ||
|
||
Back in the trigger, change the channel to Production instead. | ||
|
||
:::figure | ||
![Helm chart trigger production channel](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-trigger-production-channel.png) | ||
::: | ||
|
||
New releases will remain undeployed until someone has time to manually review the changes and click **Deploy**. | ||
|
||
:::figure | ||
![Helm chart undeployed release](/docs/deployments/kubernetes/automatically-track-third-party-helm-charts/helm-chart-undeployed-release.png) | ||
::: | ||
|
||
These are two simple cases, take a look at [environment recommendations](/docs/infrastructure/environments/environment-recommendations) for more information on what's possible. | ||
|
||
#### Getting notified about new releases | ||
|
||
Now you have a list of releases created and waiting to be deployed. This isn't very useful if no one knows about it. | ||
|
||
Octopus deploy offers a quick and easy notification service through [subscriptions](/docs/administration/managing-infrastructure/subscriptions) that allow you to send the right people an email or message whenever a release is created in a particular project. |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -13,17 +13,18 @@ navOrder: 8 | |
|
||
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**. | ||
|
@@ -49,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. | ||
|
@@ -67,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! | ||
|
@@ -82,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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Might be worth adding something here to note that the image doesn't have to be downloaded for this to work. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm gonna leave this as is, I don't think anything implies this will or won't download the image and the information likely belongs elsewhere. I'm pretty sure the UI says it won't be downloaded somewhere too, so I'm not concerned. |
||
|
||
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. | ||
``` | ||
|
||
```glob | ||
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. | ||
``` | ||
|
||
```glob | ||
**/*.{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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It might be good to add a link to the target tag page, given that they've recently been renamed from roles.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good idea