From 67683dd8dff9434d8ea583dcb995af09806c157f Mon Sep 17 00:00:00 2001 From: John Simons Date: Fri, 18 Aug 2023 16:01:29 +1000 Subject: [PATCH 1/8] kustomize docs --- .../kubernetes/deploy-raw-yaml/index.md | 49 +------------------ .../deployments/kubernetes/glob-patterns.md | 39 +++++++++++++++ .../deployments/kubernetes/kubectl/index.md | 2 +- .../deployments/kubernetes/kustomize/index.md | 47 ++++++++++++++++++ 4 files changed, 88 insertions(+), 49 deletions(-) create mode 100644 src/pages/docs/deployments/kubernetes/glob-patterns.md create mode 100644 src/pages/docs/deployments/kubernetes/kustomize/index.md diff --git a/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md b/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md index 237162bfe4..17b222b1f2 100644 --- a/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md +++ b/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md @@ -98,52 +98,5 @@ There are a few different ways to take advantage of this feature: **Note:** *If multiple glob patterns find the same file, the file will be applied twice.* -### Glob Pattern Cheat Sheet -Patterns are always relative so start them with a file or folder name. eg: `my/folder/*.yml` and `**/dep.yml`. - -:::div{.warning} -Directory separators should be forward slashes `/` for all platforms. Backslashes `\` only work when the server and worker are running on Windows. -::: - -:::div{.hint} -Glob patterns cannot contain folders stemming from a root directory. eg: `/` and `C:\` - -Glob patterns cannot start with a relative path indicator. eg: `./` and `.\` - -The directory traversal path `../` is not supported. -::: - -`?` matches any single character in a file or directory name: -``` -deployments/resource-?.yaml => deployments/resource-1.yaml, deployments/resource-g.yaml -``` - -`*` matches zero or more characters in a file or directory name: -``` -deployments/*.yaml => deployments/anything-here.yaml, deployments/123-another-file.yaml -*/resource.yaml => deployments/resource.yaml, services/resource.yaml -``` - -`**` matches zero or more recursive directories: -``` -**/resource.yaml => deployments/resource.yaml, services/resource.yaml, deployments/child-folder/resource.yaml -``` - -:::div{.hint} -**Group pattern matching is coming soon**! - -`[123]` matches a set of characters in a name. Syntax is similar to character groups in Regex: -``` -deployments/resource-[123].yaml => deployments/resource-1.yaml, deployments/resource-2.yaml, deployments/resource-3.yaml -"deployments/resource-g.yaml" would not match the example glob pattern. - -deployments/resource-[1-3].yaml => deployments/resource-1.yaml, deployments/resource-2.yaml, deployments/resource-3.yaml -"deployments/resource-g.yaml" would not match the example glob pattern. -``` - -`{abc,123,xyz}` matches any of the comma separated strings: -``` -deployments/resource-{123,abc}.yaml => deployments/resource-123.yaml, deployments/resource-abc.yaml -``` -::: \ No newline at end of file +[Learn more about glob patterns](/docs/deployments/kubernetes/glob-patterns.md). diff --git a/src/pages/docs/deployments/kubernetes/glob-patterns.md b/src/pages/docs/deployments/kubernetes/glob-patterns.md new file mode 100644 index 0000000000..c7995e2a4d --- /dev/null +++ b/src/pages/docs/deployments/kubernetes/glob-patterns.md @@ -0,0 +1,39 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2023-01-01 +modDate: 2023-01-01 +title: Glob Pattern Cheat Sheet +description: Learn more about glob patterns usages. +navOrder: 90 +--- + + +Patterns are always relative so start them with a file or folder name. eg: `my/folder/*.yml` and `**/dep.yml`. + +:::div{.warning} +Directory separators should be forward slashes `/` for all platforms. Backslashes `\` only work when the server and worker are running on Windows. +::: + +:::div{.hint} +Glob patterns cannot contain folders stemming from a root directory. eg: `/` and `C:\` + +Glob patterns cannot start with a relative path indicator. eg: `./` and `.\` + +The directory traversal path `../` is not supported. +::: + +`?` matches any single character in a file or directory name: +``` +deployments/resource-?.yaml => deployments/resource-1.yaml, deployments/resource-g.yaml +``` + +`*` matches zero or more characters in a file or directory name: +``` +deployments/*.yaml => deployments/anything-here.yaml, deployments/123-another-file.yaml +*/resource.yaml => deployments/resource.yaml, services/resource.yaml +``` + +`**` matches zero or more recursive directories: +``` +**/resource.yaml => deployments/resource.yaml, services/resource.yaml, deployments/child-folder/resource.yaml +``` \ No newline at end of file diff --git a/src/pages/docs/deployments/kubernetes/kubectl/index.md b/src/pages/docs/deployments/kubernetes/kubectl/index.md index aeaed48320..c6b3501559 100644 --- a/src/pages/docs/deployments/kubernetes/kubectl/index.md +++ b/src/pages/docs/deployments/kubernetes/kubectl/index.md @@ -9,6 +9,6 @@ navOrder: 100 The [kubectl command-line tool](https://kubernetes.io/docs/reference/kubectl/overview/) is required by Octopus Deploy's Kubernetes features. -kubectl is not bundled with Octopus, and must be pre-installed on the [worker](/docs/infrastructure/workers/) or Octopus Server which will execute steps and health checks against a [Kubernetes target](/docs/infrastructure/deployment-targets/kubernetes-target/). Alternatively, [execution containers](/docs/projects/steps/execution-containers-for-workers) may be used. +kubectl is not bundled with Octopus, and must be pre-installed on the [worker](/docs/infrastructure/workers/) or Octopus Server which will execute steps and health checks against a [Kubernetes target](/docs/infrastructure/deployment-targets/kubernetes-target/). Alternatively, [execution containers](/docs/projects/steps/execution-containers-for-workers) may be used and we recommend using `[octopuslabs/k8s-workertools](https://hub.docker.com/r/octopuslabs/k8s-workertools)` docker image, we also recommend setting the tag to a version that is compatible with the version of your cluster, [read the official version skew policy](https://kubernetes.io/releases/version-skew-policy/#kubectl) for more information. By default, Octopus assumes `kubectl` is available in the PATH environment variable. A specific location for `kubectl` can be supplied by setting a `Octopus.Action.Kubernetes.CustomKubectlExecutable` variable in the Octopus project (an example value is `c:\tools\kubectl\version\kubectl.exe`). diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md new file mode 100644 index 0000000000..a059b1dd1a --- /dev/null +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -0,0 +1,47 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2023-01-01 +modDate: 2023-01-01 +title: kustomize +description: Use kustomize to deploy resources to a Kubernetes cluster. +navOrder: 9 +--- + +Octopus supports the deployment of Kubernetes resources through the `kustomize` step. + +This step allows you to source your kustomize files from git, perform variable substitutions based on your environment and/or tenant and finally apply the changes to your Kubernetes clusters. + +[Kustomize](https://kustomize.io) introduces a template-free way to customize application configuration that simplifies the use of off-the-shelf applications. + +## Recommended usages for this step + +We list three different scenarios below to help you figure out what is the best setup for you to deploy your applications to a Kubernetes cluster with Octopus. + +1. **The kustomize way** + This is the recommended usage if you are already using Kustomize and just want Octopus to orchestrate the deployment. + In this screnario our recomendation is to use `.env` files with Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions), so we can replace secrets and any other data managed via Octopus variables. These `.env` files are then used by [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_) and/or [configMapGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_). + Everything else is defined in the `kustomization.yaml` files directly and overlays should match the same environment structure defined in Octopus itself. + +2. **No overlays** + In this scenario you may define two overlays, one being for local use outside Octopus, so you can test your `yaml`` files. The other overlay is used exclusively by Octopus. + In the Octopus overlay you add [variable substitution syntax](/docs/projects/variables/variable-substitutions) directly into `kustomization.yaml` and any other `yaml` files in the overlay folder, as well as `.env` files. + This scenario is better suited for customers with many environments and/or tenants, where customisations are needed for each target. + +3. **A mix of both!** + This would be the ideal scenario when you have a small number of environments and many tenants. + In this scenario you model your overlays based on the environments, with the different setting hardcoded in the `kustomization.yaml` file, and you use Octopus [substitution syntax](/docs/projects/variables/variable-substitutions) to define the different tenant properties in `kustomization.yaml` file. + Again as the previous scenarios, we would use `.env` files for secrets via [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_). + + +## kustomization file directory + +This field must be a path to a directory containing the `kustomization.yaml` file. +The path is relative to the root of the git repository. +When using overlays ensure the path is to the overlay directory containing `kustomization.yaml` file. +Also remember that in Linux workers, the paths are case sensitive, so it is always good practice to check this. + +## Substitute Variables in Files + +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.md). \ No newline at end of file From e727ffbc98ec7564d65eae5e8ac53059f946b5a4 Mon Sep 17 00:00:00 2001 From: Kit <114034230+nikita-dergilev@users.noreply.github.com> Date: Mon, 21 Aug 2023 17:13:18 +1200 Subject: [PATCH 2/8] Update index.md --- .../deployments/kubernetes/kustomize/index.md | 32 ++++++++++++------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md index a059b1dd1a..58e1ea4b7b 100644 --- a/src/pages/docs/deployments/kubernetes/kustomize/index.md +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -15,33 +15,41 @@ This step allows you to source your kustomize files from git, perform variable s ## Recommended usages for this step -We list three different scenarios below to help you figure out what is the best setup for you to deploy your applications to a Kubernetes cluster with Octopus. +We list a few different scenarios below to help you figure out what is the best setup for you to deploy your applications to a Kubernetes cluster with Octopus. + +*When you use Kustomize for one application configuration* 1. **The kustomize way** This is the recommended usage if you are already using Kustomize and just want Octopus to orchestrate the deployment. - In this screnario our recomendation is to use `.env` files with Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions), so we can replace secrets and any other data managed via Octopus variables. These `.env` files are then used by [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_) and/or [configMapGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_). - Everything else is defined in the `kustomization.yaml` files directly and overlays should match the same environment structure defined in Octopus itself. + In this scenario, our recommendation is to use `.env` files with Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions), so we can replace secrets and any other data managed via Octopus variables. These `.env` files are then used by [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_) and/or [configMapGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_). + Everything else is defined in the `kustomization.yaml` files directly, and overlays should match the same environment structure defined in Octopus itself. 2. **No overlays** - In this scenario you may define two overlays, one being for local use outside Octopus, so you can test your `yaml`` files. The other overlay is used exclusively by Octopus. - In the Octopus overlay you add [variable substitution syntax](/docs/projects/variables/variable-substitutions) directly into `kustomization.yaml` and any other `yaml` files in the overlay folder, as well as `.env` files. + In this scenario, you may define two overlays, one being for local use outside Octopus, so you can test your `yaml` files. The other overlay is used exclusively by Octopus. + In the Octopus overlay, you add [variable substitution syntax](/docs/projects/variables/variable-substitutions) directly into `kustomization.yaml` and any other `yaml` files in the overlay folder, as well as `.env` files. This scenario is better suited for customers with many environments and/or tenants, where customisations are needed for each target. 3. **A mix of both!** This would be the ideal scenario when you have a small number of environments and many tenants. - In this scenario you model your overlays based on the environments, with the different setting hardcoded in the `kustomization.yaml` file, and you use Octopus [substitution syntax](/docs/projects/variables/variable-substitutions) to define the different tenant properties in `kustomization.yaml` file. - Again as the previous scenarios, we would use `.env` files for secrets via [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_). + In this scenario, you model your overlays based on the environments, with the different settings hardcoded in the `kustomization.yaml` file, and you use Octopus [substitution syntax](/docs/projects/variables/variable-substitutions) to define the different tenant properties in `kustomization.yaml` file. + Again as in the previous scenarios, we would use `.env` files for secrets via [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_). + +*When you use Kustomize to template configurations for many applications* +4. **A mix of both — templates** + You can go beyond configuration for a single application with Octopus and Kustomize. Imagine you have a hundred applications you deploy to Kubernetes. Some of them might have universal traits, like a group of API applications or a group of databases. Therefore, parts of the configuration will be universal for all the apps or a group of apps. There likely be app-unique parameters (like a container image). + You can combine overlays and Octopus variables to create and use one template for all the apps. In this scenario, you would have a set of base files same for all the apps. One or more levels of overlays to add customizations for an app group. You can introduce another layer of overlays for environments. Finally, app-specific parameters (e.g. container images, tags and labels) can be defined in Octopus variables. + In this scenario, tenant or environment-specific parameters can be added to any overlay. For example, you can add prefixes for tenants; also consider using [system variables](https://octopus.com/docs/projects/variables/system-variables). -## kustomization file directory +## Kustomization file directory This field must be a path to a directory containing the `kustomization.yaml` file. The path is relative to the root of the git repository. -When using overlays ensure the path is to the overlay directory containing `kustomization.yaml` file. -Also remember that in Linux workers, the paths are case sensitive, so it is always good practice to check this. +When using overlays, ensure the path is to the overlay directory containing `kustomization.yaml` file. +Also, remember that in Linux workers, the paths are case-sensitive, so it is always good practice to check this. ## Substitute Variables in Files 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.md). \ No newline at end of file +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.md). From cee2554ff3b9e46bff40fa9f848a81efcf45af8e Mon Sep 17 00:00:00 2001 From: John Simons Date: Tue, 22 Aug 2023 13:47:26 +1000 Subject: [PATCH 3/8] more introductory text --- src/pages/docs/deployments/kubernetes/kustomize/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md index 58e1ea4b7b..9f6f78a86a 100644 --- a/src/pages/docs/deployments/kubernetes/kustomize/index.md +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -44,12 +44,14 @@ We list a few different scenarios below to help you figure out what is the best ## Kustomization file directory This field must be a path to a directory containing the `kustomization.yaml` file. +During deployment, `Kustomize` reads the `kustomization.yaml` file located at this path to perform manifest yaml transforms. The path is relative to the root of the git repository. When using overlays, ensure the path is to the overlay directory containing `kustomization.yaml` file. Also, remember that in Linux workers, the paths are case-sensitive, so it is always good practice to check this. ## 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). 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.md). From 2d48b164ad275d7918ed2f50f471964cf4515f92 Mon Sep 17 00:00:00 2001 From: John Simons Date: Tue, 22 Aug 2023 13:50:20 +1000 Subject: [PATCH 4/8] Better wording --- src/pages/docs/deployments/kubernetes/kustomize/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md index 9f6f78a86a..1b439b2f52 100644 --- a/src/pages/docs/deployments/kubernetes/kustomize/index.md +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -19,17 +19,17 @@ We list a few different scenarios below to help you figure out what is the best *When you use Kustomize for one application configuration* -1. **The kustomize way** +1. **Multiple overlays** This is the recommended usage if you are already using Kustomize and just want Octopus to orchestrate the deployment. In this scenario, our recommendation is to use `.env` files with Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions), so we can replace secrets and any other data managed via Octopus variables. These `.env` files are then used by [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_) and/or [configMapGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_). Everything else is defined in the `kustomization.yaml` files directly, and overlays should match the same environment structure defined in Octopus itself. -2. **No overlays** +2. **Single overlay for Octopus** In this scenario, you may define two overlays, one being for local use outside Octopus, so you can test your `yaml` files. The other overlay is used exclusively by Octopus. In the Octopus overlay, you add [variable substitution syntax](/docs/projects/variables/variable-substitutions) directly into `kustomization.yaml` and any other `yaml` files in the overlay folder, as well as `.env` files. This scenario is better suited for customers with many environments and/or tenants, where customisations are needed for each target. -3. **A mix of both!** +3. **A mix of both** This would be the ideal scenario when you have a small number of environments and many tenants. In this scenario, you model your overlays based on the environments, with the different settings hardcoded in the `kustomization.yaml` file, and you use Octopus [substitution syntax](/docs/projects/variables/variable-substitutions) to define the different tenant properties in `kustomization.yaml` file. Again as in the previous scenarios, we would use `.env` files for secrets via [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_). From 8f7240bac66d2b175fe8ee5c3d995a2d5e60e84d Mon Sep 17 00:00:00 2001 From: John Simons Date: Tue, 22 Aug 2023 13:53:04 +1000 Subject: [PATCH 5/8] Better formatting --- src/pages/docs/deployments/kubernetes/kustomize/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md index 1b439b2f52..d4f122508f 100644 --- a/src/pages/docs/deployments/kubernetes/kustomize/index.md +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -17,7 +17,7 @@ This step allows you to source your kustomize files from git, perform variable s We list a few different scenarios below to help you figure out what is the best setup for you to deploy your applications to a Kubernetes cluster with Octopus. -*When you use Kustomize for one application configuration* +### When you use Kustomize for one application configuration 1. **Multiple overlays** This is the recommended usage if you are already using Kustomize and just want Octopus to orchestrate the deployment. @@ -34,9 +34,9 @@ We list a few different scenarios below to help you figure out what is the best In this scenario, you model your overlays based on the environments, with the different settings hardcoded in the `kustomization.yaml` file, and you use Octopus [substitution syntax](/docs/projects/variables/variable-substitutions) to define the different tenant properties in `kustomization.yaml` file. Again as in the previous scenarios, we would use `.env` files for secrets via [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_). -*When you use Kustomize to template configurations for many applications* +### When you use Kustomize to template configurations for many applications -4. **A mix of both — templates** +1. **A mix of both — templates** You can go beyond configuration for a single application with Octopus and Kustomize. Imagine you have a hundred applications you deploy to Kubernetes. Some of them might have universal traits, like a group of API applications or a group of databases. Therefore, parts of the configuration will be universal for all the apps or a group of apps. There likely be app-unique parameters (like a container image). You can combine overlays and Octopus variables to create and use one template for all the apps. In this scenario, you would have a set of base files same for all the apps. One or more levels of overlays to add customizations for an app group. You can introduce another layer of overlays for environments. Finally, app-specific parameters (e.g. container images, tags and labels) can be defined in Octopus variables. In this scenario, tenant or environment-specific parameters can be added to any overlay. For example, you can add prefixes for tenants; also consider using [system variables](https://octopus.com/docs/projects/variables/system-variables). From cf8dfa56bc2963ad929f488f464b34fd716b7ab3 Mon Sep 17 00:00:00 2001 From: John Simons Date: Tue, 22 Aug 2023 14:07:30 +1000 Subject: [PATCH 6/8] More formatting --- .../deployments/kubernetes/kustomize/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md index d4f122508f..be823ef6a8 100644 --- a/src/pages/docs/deployments/kubernetes/kustomize/index.md +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -21,17 +21,17 @@ We list a few different scenarios below to help you figure out what is the best 1. **Multiple overlays** This is the recommended usage if you are already using Kustomize and just want Octopus to orchestrate the deployment. - In this scenario, our recommendation is to use `.env` files with Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions), so we can replace secrets and any other data managed via Octopus variables. These `.env` files are then used by [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_) and/or [configMapGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_). + In this scenario, our recommendation is to use `.env` files with Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions), so we can replace secrets and any other data managed via Octopus variables. These `.env` files are then used by [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_) and/or [configMapGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_). Everything else is defined in the `kustomization.yaml` files directly, and overlays should match the same environment structure defined in Octopus itself. 2. **Single overlay for Octopus** - In this scenario, you may define two overlays, one being for local use outside Octopus, so you can test your `yaml` files. The other overlay is used exclusively by Octopus. - In the Octopus overlay, you add [variable substitution syntax](/docs/projects/variables/variable-substitutions) directly into `kustomization.yaml` and any other `yaml` files in the overlay folder, as well as `.env` files. + In this scenario, you may define two overlays, one being for local use outside Octopus, so you can test your `yaml` files. The other overlay is used exclusively by Octopus. + In the Octopus overlay, you add [variable substitution syntax](/docs/projects/variables/variable-substitutions) directly into `kustomization.yaml` and any other `yaml` files in the overlay folder, as well as `.env` files. This scenario is better suited for customers with many environments and/or tenants, where customisations are needed for each target. 3. **A mix of both** - This would be the ideal scenario when you have a small number of environments and many tenants. - In this scenario, you model your overlays based on the environments, with the different settings hardcoded in the `kustomization.yaml` file, and you use Octopus [substitution syntax](/docs/projects/variables/variable-substitutions) to define the different tenant properties in `kustomization.yaml` file. + This would be the ideal scenario when you have a small number of environments and many tenants. + In this scenario, you model your overlays based on the environments, with the different settings hardcoded in the `kustomization.yaml` file, and you use Octopus [substitution syntax](/docs/projects/variables/variable-substitutions) to define the different tenant properties in `kustomization.yaml` file. Again as in the previous scenarios, we would use `.env` files for secrets via [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_). ### When you use Kustomize to template configurations for many applications @@ -44,14 +44,14 @@ We list a few different scenarios below to help you figure out what is the best ## Kustomization file directory This field must be a path to a directory containing the `kustomization.yaml` file. -During deployment, `Kustomize` reads the `kustomization.yaml` file located at this path to perform manifest yaml transforms. +During deployment, `Kustomize` reads the `kustomization.yaml` file located at this path to perform manifest yaml transforms. The path is relative to the root of the git repository. -When using overlays, ensure the path is to the overlay directory containing `kustomization.yaml` file. +When using overlays, ensure the path is to the overlay directory containing `kustomization.yaml` file. Also, remember that in Linux workers, the paths are case-sensitive, so it is always good practice to check this. ## 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#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. +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.md). From 8ea8aa56aa601362f53c92a63cc7739e1e6f8865 Mon Sep 17 00:00:00 2001 From: John Simons Date: Tue, 22 Aug 2023 15:16:02 +1000 Subject: [PATCH 7/8] more formatting --- src/pages/docs/deployments/kubernetes/kustomize/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md index be823ef6a8..07383620d4 100644 --- a/src/pages/docs/deployments/kubernetes/kustomize/index.md +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -7,9 +7,9 @@ description: Use kustomize to deploy resources to a Kubernetes cluster. navOrder: 9 --- -Octopus supports the deployment of Kubernetes resources through the `kustomize` step. +Octopus supports the deployment of Kubernetes resources through the **kustomize** step. -This step allows you to source your kustomize files from git, perform variable substitutions based on your environment and/or tenant and finally apply the changes to your Kubernetes clusters. +This step allows you to source your **kustomize** files from git, perform variable substitutions based on your environment and/or tenant and finally apply the changes to your Kubernetes clusters. [Kustomize](https://kustomize.io) introduces a template-free way to customize application configuration that simplifies the use of off-the-shelf applications. @@ -44,7 +44,7 @@ We list a few different scenarios below to help you figure out what is the best ## Kustomization file directory This field must be a path to a directory containing the `kustomization.yaml` file. -During deployment, `Kustomize` reads the `kustomization.yaml` file located at this path to perform manifest yaml transforms. +During deployment, **Kustomize** reads the `kustomization.yaml` file located at this path to perform manifest yaml transforms. The path is relative to the root of the git repository. When using overlays, ensure the path is to the overlay directory containing `kustomization.yaml` file. Also, remember that in Linux workers, the paths are case-sensitive, so it is always good practice to check this. From ecbe3f790ba50509969428e226a0865dcb2df2cc Mon Sep 17 00:00:00 2001 From: John Simons Date: Wed, 23 Aug 2023 12:33:19 +1000 Subject: [PATCH 8/8] Fix links --- .../docs/deployments/kubernetes/deploy-raw-yaml/index.md | 2 +- src/pages/docs/deployments/kubernetes/kustomize/index.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md b/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md index 17b222b1f2..0346b06e08 100644 --- a/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md +++ b/src/pages/docs/deployments/kubernetes/deploy-raw-yaml/index.md @@ -99,4 +99,4 @@ There are a few different ways to take advantage of this feature: **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.md). +[Learn more about glob patterns](/docs/deployments/kubernetes/glob-patterns). diff --git a/src/pages/docs/deployments/kubernetes/kustomize/index.md b/src/pages/docs/deployments/kubernetes/kustomize/index.md index 07383620d4..399e5230c5 100644 --- a/src/pages/docs/deployments/kubernetes/kustomize/index.md +++ b/src/pages/docs/deployments/kubernetes/kustomize/index.md @@ -39,7 +39,7 @@ We list a few different scenarios below to help you figure out what is the best 1. **A mix of both — templates** You can go beyond configuration for a single application with Octopus and Kustomize. Imagine you have a hundred applications you deploy to Kubernetes. Some of them might have universal traits, like a group of API applications or a group of databases. Therefore, parts of the configuration will be universal for all the apps or a group of apps. There likely be app-unique parameters (like a container image). You can combine overlays and Octopus variables to create and use one template for all the apps. In this scenario, you would have a set of base files same for all the apps. One or more levels of overlays to add customizations for an app group. You can introduce another layer of overlays for environments. Finally, app-specific parameters (e.g. container images, tags and labels) can be defined in Octopus variables. - In this scenario, tenant or environment-specific parameters can be added to any overlay. For example, you can add prefixes for tenants; also consider using [system variables](https://octopus.com/docs/projects/variables/system-variables). + In this scenario, tenant or environment-specific parameters can be added to any overlay. For example, you can add prefixes for tenants; also consider using [system variables](/docs/projects/variables/system-variables). ## Kustomization file directory @@ -54,4 +54,4 @@ Also, remember that in Linux workers, the paths are case-sensitive, so it is alw 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). 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.md). +You can use glob patterns to target multiple files. [Learn more about glob patterns](/docs/deployments/kubernetes/glob-patterns).