diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt index a235399991..f2a4824e9a 100644 --- a/dictionary-octopus.txt +++ b/dictionary-octopus.txt @@ -110,6 +110,7 @@ emptytitle entra environmentids eprintfn +esac expressjs externalgroups externalusers @@ -421,6 +422,7 @@ tfvar tfvars TFVC thepassword +timespan tlsv1 tmpfs Toolsets diff --git a/public/docs/infrastructure/deployment-targets/azure/web-app-targets/create-azure-web-app-target.png b/public/docs/infrastructure/deployment-targets/azure/web-app-targets/create-azure-web-app-target.png index ba40ee07f3..9ec27ad9b4 100644 Binary files a/public/docs/infrastructure/deployment-targets/azure/web-app-targets/create-azure-web-app-target.png and b/public/docs/infrastructure/deployment-targets/azure/web-app-targets/create-azure-web-app-target.png differ diff --git a/public/docs/infrastructure/deployment-targets/azure/web-app-targets/deployment-targets-web-app-healthy.png b/public/docs/infrastructure/deployment-targets/azure/web-app-targets/deployment-targets-web-app-healthy.png index a32d3f7515..db48a7cdaf 100644 Binary files a/public/docs/infrastructure/deployment-targets/azure/web-app-targets/deployment-targets-web-app-healthy.png and b/public/docs/infrastructure/deployment-targets/azure/web-app-targets/deployment-targets-web-app-healthy.png differ diff --git a/src/pages/docs/deployments/azure/cloud-services/getting-started-with-azure-cloud-services.md b/src/pages/docs/deployments/azure/cloud-services/getting-started-with-azure-cloud-services.md index c3e70aef17..0de26c0c72 100644 --- a/src/pages/docs/deployments/azure/cloud-services/getting-started-with-azure-cloud-services.md +++ b/src/pages/docs/deployments/azure/cloud-services/getting-started-with-azure-cloud-services.md @@ -1,9 +1,9 @@ --- layout: src/layouts/Redirect.astro title: Redirect -redirect: https://octopus.com/docs/deployments/azure/cloud-services +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure pubDate: 2023-01-01 navSearch: false navSitemap: false navMenu: false ---- +--- \ No newline at end of file diff --git a/src/pages/docs/deployments/azure/cloud-services/index.md b/src/pages/docs/deployments/azure/cloud-services/index.md new file mode 100644 index 0000000000..1ec753541e --- /dev/null +++ b/src/pages/docs/deployments/azure/cloud-services/index.md @@ -0,0 +1,10 @@ +--- +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure +pubDate: 2023-01-01 +navSearch: false +navSitemap: false +navMenu: false +hideInThisSectionHeader: true +--- \ No newline at end of file diff --git a/src/pages/docs/deployments/azure/cloud-services/index.mdx b/src/pages/docs/deployments/azure/cloud-services/index.mdx deleted file mode 100644 index 343b0f7b74..0000000000 --- a/src/pages/docs/deployments/azure/cloud-services/index.mdx +++ /dev/null @@ -1,188 +0,0 @@ ---- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2023-01-01 -title: Azure Cloud Services -description: Octopus Deploy can help you perform repeatable and controlled deployments to Azure Cloud Services. -hideInThisSectionHeader: true ---- -import AzureCloudServicesDeprecated from 'src/shared-content/deprecated-items/azure-cloud-services-deprecated.include.md'; - - - -Octopus Deploy supports deployment of [Azure Cloud Services](http://azure.microsoft.com/en-us/services/cloud-services/). This page will walk you through, step by step, setting up a deployment using the Octopus built-in **Deploy an Azure Cloud Service** step. - -## Step 1: Packaging - -An Azure cloud service package is normally compiled into a `.cspkg` file. This file will need to be [re-packed into a supported package](/docs/packaging-applications) for Octopus to consume. The easiest way to do this currently is to either create a simple zip file or use the [NuGet.exe command line tool](https://docs.microsoft.com/en-us/nuget/tools/nuget-exe-cli-reference). For example, the resulting NuGet package will look like this: - -:::figure -![](/docs/deployments/azure/cloud-services/3278363.png "width=500") -::: - -### Upload to a NuGet feed - -In order to make the NuGet package accessible to Octopus it needs to be uploaded to a [package repository](/docs/packaging-applications/package-repositories). The built-in Octopus package repository is accessible from **Library ➜ Packages** and is a suitable place to upload your Cloud Service NuGet package: - -:::figure -![Package feed](/docs/deployments/azure/cloud-services/package-feed.png "width=500") -::: - -## Step 2: Create an Azure account - -If you haven't already, create an [Azure Management Certificate Account](/docs/infrastructure/accounts/azure) to grant Octopus Deploy access to your Azure Subscription. - -## Step 3: Create the Azure Cloud Service deployment step - -Add a new Azure Cloud Service Deployment Step to your project. For information about adding a step to the deployment process, see the [add step](/docs/projects/steps) section. - -:::figure -![](/docs/deployments/azure/cloud-services/5865904.png "width=170") -::: - -## Step 4: Configure your Azure Cloud Service step - -Once an Account is selected, the list of Cloud Services and Storage Accounts available to the Azure subscription associated with the chosen Account will be populated for you to choose from. - -| Setting | Default | Description | -| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Account | | The [Azure Account](/docs/infrastructure/accounts/azure/) you want to target when deploying this cloud service. Select one from the list, or use a [variable binding](/docs/projects/variables/variable-substitutions) to select an account by its name or ID. | -| Cloud Service | | The actual cloud service you want to target. Select one from the list, or use a [variable binding](/docs/projects/variables/variable-substitutions) to define the name of the cloud service. | -| Storage Account | | The Azure Storage Account where the Cloud Service Package (`*.cspkg`) file will be pushed in order to be deployed. | -| Slot | | You can choose to deploy to either the Staging or Production slot. | -| Swap | | Azure allows staging and production deployments to be swapped, by switching virtual IP addresses. When deploying to production, Octopus can detect whether the current staging deployment can be swapped, and if so, it can do a swap rather than a new deployment.
If **Always deploy** is selected, the package will always be deployed to the selected Slot.
If **Swap staging to production if possible** is selected and the selected Slot is Production, then a swap will occur between Production and Staging (if there is a deployment in the Staging slot).
See [VIP Swap](/docs/deployments/azure/cloud-services/vip-swap) for more information on how to configure a VIP swap. | -| Instance Count | | If you have scaled your Windows Azure service using the management portal (for example, changing the role count from 1 to 4), during a deployment Octopus can be configured to keep the existing instance counts rather than using the instance counts defined in your cloud service configuration file. | - -:::div{.success} -**Use variable binding expressions** -Any of the settings above can be switched to use a variable binding expression. A common example is when you use a naming convention for your different cloud services, like **MyCloudService_Production** and **MyCloudService_Test** - you can use environment-scoped variables to automatically configure this step depending on the environment you are targeting. -::: - -### Deployment features available to Azure Cloud Service steps - -The following features are available when deploying a package to an Azure Cloud Service: - -- [Custom Scripts](/docs/deployments/custom-scripts) -- [Configuration Variables](/docs/projects/steps/configuration-features/xml-configuration-variables-feature) -- [.NET Configuration Transforms](/docs/projects/steps/configuration-features/configuration-transforms) -- [Structured configuration variables](/docs/projects/steps/configuration-features/structured-configuration-variables-feature) -- [Substitute variables in templates](/docs/projects/steps/configuration-features/substitute-variables-in-templates) - -Please note these features actually run on the Octopus Server prior to deploying the Cloud Service package to Azure. They don't execute in the Azure Cloud Service instances you are eventually targeting. - -#### Using custom scripts - -[Custom scripts](/docs/deployments/custom-scripts) typically rely on specific tools being available when they execute. - -It is best that you control the version of these tools - your scripts will rely on a specific version that they are compatible with to function correctly. - -The easiest way to achieve this is to use an [execution container](/docs/projects/steps/execution-containers-for-workers) for your step. - -If this is not an option in your scenario, we recommend that you provision your own tools on your worker. - -:::div{.warning} -Using the Azure tools bundled with Octopus Deploy is not recommended. Octopus bundles versions of the Azure Resource Manager Powershell modules (AzureRM) and Azure CLI. These were originally provided as convenience mechanisms for users wanting to run scripts against Azure targets. The versions bundled are now out of date, and we will not be updating them further. - -From **Octopus 2021.2**, a warning will also appear in the deployment logs if the Azure tools bundled with Octopus Deploy are used in a step. - -We recommend you configure Octopus Deploy to use your own [version of the Azure PowerShell cmdlets](/docs/deployments/azure/running-azure-powershell/configuring-the-version-of-the-azure-powershell-modules/) and [version of the Azure CLI](/docs/deployments/azure/running-azure-powershell/configuring-the-version-of-the-azure-cli). -::: - -If the Azure PowerShell module is available, it will be loaded for your convenience, and the subscription from the account associated with the target will be selected. This means you don't have to worry about loading the Azure PowerShell module nor authenticating with Azure yourself. - -You can write very straightforward scripts like the example below: - -```powershell -# Swap the staging slot into production -$ServiceName = $OctopusParameters["Octopus.Action.Azure.CloudServiceName"] -$Deployment = Get-AzureDeployment -Slot "Staging" -ServiceName $ServiceName -if ($Deployment -ne $null -AND $Deployment.DeploymentId -ne $null) { - Write-Host ("Current Status of staging slot for {0}" -f $ServiceName) - $Deployment - $MoveStatus = Move-AzureDeployment -ServiceName $ServiceName - Write-Host ("Vip swap of {0} status: {1}" -f $ServiceName, $MoveStatus.OperationStatus) -} else { - Write-Host ("There is no deployment in staging slot of {0} to swap." -f $ServiceName) -} -``` -See the [Azure PowerShell documentation](/docs/deployments/azure/running-azure-powershell) for more information. - -## Deployment process - -Deployment to an Azure Cloud Service proceeds as follows (more details provided below): - -1. Download the package from the [package repository](/docs/packaging-applications/package-repositories). -2. Extract the package on the Octopus Server to a temporary location. -3. Extract the Cloud Service package (`.cspkg`) to a temporary location. -4. Any configured or packaged `PreDeploy` scripts are executed. -5. Variable substitutions in Cloud Service configuration file (`.cscfg`). -6. [Substitute variables in templates](/docs/projects/steps/configuration-features/substitute-variables-in-templates) (if configured). -7. [.NET XML configuration transformations](/docs/projects/steps/configuration-features/configuration-transforms) (if configured) are performed. -8. [.NET XML configuration variables](/docs/projects/steps/configuration-features/xml-configuration-variables-feature) (if configured) are replaced. -9. Any configured or package `Deploy` scripts are executed. -10. Re-package the Cloud Service Package. -11. Upload the Cloud Service Package to Azure Storage. -12. Deploy the Cloud Service Package (see 'Customizing the deployment process' section below). -13. Any configured or packaged `PostDeploy` scripts are executed. - -### Extract the Cloud Service package - -Cloud Service Package files are extracted during deployment, in order to make available features such as .NET Configuration Transforms and Variable Substitution. - -To extract the Cloud Service Package, it is first converted to the CTP format (also known as V20120315). This is the format described by Microsoft [documentation](https://msdn.microsoft.com/en-us/library/azure/jj151522.aspx), but is not used by default by the [CSPack ](https://msdn.microsoft.com/en-us/library/azure/gg432988.aspx)utility (passing the `/useCtpPackageFormat` switch is required for this format to be used). This is just an implementation detail, but the documented archive layout gives a good starting point to understanding the layout of the extracted package. - -Setting the `Octopus.Action.Azure.LogExtractedCspkg` variable to `true` will cause the layout of the extracted package to be written into the Task Log. This may assist with finding the path to a particular file. - -:::div{.warning} -**Disable Package Extraction and Re-Packaging** - -Based on customer reports and Azure community discussions, we believe Microsoft is no longer recommending Azure Cloud Services: https://docs.microsoft.com/en-us/azure/architecture/guide/technology-choices/compute-decision-tree. Several customers have reported timeout issues in regards to Azure Cloud Services and slow re-packing of CTP packages. Unfortunately, we cannot fix this issue, [as noted here](https://github.com/OctopusDeploy/Issues/issues/6111). - -The issues around timeouts and slow re-repackaging can be mitigated by passing in the variable `Octopus.Action.Azure.CloudServicePackageExtractionDisabled` and setting the value to `true`. However, in doing so, variable substitution will no longer be available. -::: - -### Variable substitutions in Cloud Service configuration file - -Octopus will attempt to modify your `.cscfg` file. For example, take the following configuration: - -```xml - - - - - - - - - - - - - - - - -``` - -If a variable named `HelloMessage` is defined in your Octopus project variables, Octopus will automatically update it in the configuration file. You can also name the variable `Humpty.Worker/HelloMessage` to scope the setting to a specific web/worker role. - -### Customizing the deployment process - -The deployment is performed using the [open-source Calamari project](https://github.com/OctopusDeploy/Calamari). For backwards compatibility, Octopus will look for a PowerShell script called `DeployToAzure.ps1`. If a file with this name exists within your package, Octopus will invoke it. Otherwise, Octopus will continue to use it's bundled [Sashimi.AzureCloudService](https://github.com/OctopusDeploy/Sashimi.AzureCloudService) library. - -:::div{.hint} -If you choose to override the deployment script, remember that your `DeployToAzure.ps1` file must exist at **the root** of your package. It cannot be located in a subfolder. For reference, you can see how this filename is detected in your extracted package [here](https://github.com/OctopusDeploy/Sashimi.AzureCloudService/blob/main/source/Calamari/DeployAzureCloudServicePackageBehaviour.cs). -::: - -## Deploying to multiple geographic regions - -When your application is deployed to more than one geographic region, you are likely to need per-region configuration settings. You can achieve this result in many different ways, but the two most popular methods we have seen are: - -1. [Cloud Regions](/docs/infrastructure/deployment-targets/cloud-regions/): enable [rolling deployments](/docs/deployments/patterns/rolling-deployments-with-octopus) across multiple geographic regions. -2. Environment-per-region: by creating an environment per region you can leverage [lifecycles](/docs/releases/lifecycles) to create a strict release promotion process. - -Both methods allow you to modify your deployment process and variables per-region, but have slightly different release promotion paths. Choose the one that suits you best. - -## Learn more - -- Generate an Octopus guide for [Azure and the rest of your CI/CD pipeline](https://octopus.com/docs/guides?destination=Azure%20websites). diff --git a/src/pages/docs/deployments/azure/cloud-services/vip-swap.md b/src/pages/docs/deployments/azure/cloud-services/vip-swap.md new file mode 100644 index 0000000000..b38f7ce103 --- /dev/null +++ b/src/pages/docs/deployments/azure/cloud-services/vip-swap.md @@ -0,0 +1,9 @@ +--- +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure +pubDate: 2023-01-01 +navSearch: false +navSitemap: false +navMenu: false +--- \ No newline at end of file diff --git a/src/pages/docs/deployments/azure/cloud-services/vip-swap.mdx b/src/pages/docs/deployments/azure/cloud-services/vip-swap.mdx deleted file mode 100644 index 22819ae3f1..0000000000 --- a/src/pages/docs/deployments/azure/cloud-services/vip-swap.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2023-01-01 -title: VIP swap with Octopus -navTitle: VIP swap -description: The guide demonstrates how to perform a VIP swap when deploying to Azure Cloud Services. -navOrder: 1 ---- -import AzureCloudServicesDeprecated from 'src/shared-content/deprecated-items/azure-cloud-services-deprecated.include.md'; - - - -The guide demonstrates how to perform a VIP swap when deploying to Azure Cloud Services. - -## Using VIP swaps for blue/green deployments - -VIP swap is a great way for you to implement [blue/green deployments](https://octopus.com/devops/software-deployments/blue-green-deployment/) using Azure Cloud Services and Octopus Deploy. The typical process is to: - -1. Deploy a fully configured application into the "staging" slot in Azure. -2. Run manual/automated tests on your "staging" slot. -3. Perform a VIP swap, which simply swaps the "staging" and "production" slots over, resulting in your newly deployed application moving into the "production" slot and beginning to accept requests, and your previous production instance being moved down into the "staging" slot, at which point you can: - * Delete the "staging" slot to free up resources/costs. - * Keep the previous version in "staging" in case you want to roll back - which is as easy as performing another VIP swap. - -In order to complete this guide you should have a Cloud Service project set up in Octopus Deploy that is deploying to the staging or production slot. Please see our documentation for [setting up an Azure Cloud Services deployment in Octopus](/docs/deployments/azure/cloud-services) for more information. - -## Environment configuration - -The easiest way to configure Octopus for VIP swapping is to map Cloud Service slots to Octopus environments. By default a Cloud Service has a staging and production slot. In order to map this in Octopus, create Staging and Production environments: - -:::figure -![](/docs/deployments/azure/cloud-services/environments.png "width=500") -::: - -## Enabling VIP swap \{#VIPSwap-EnablingVIPswap} - -In order to enable VIP swapping, edit the process of your Cloud Service project and toggle the Swap setting to "Swap staging to production if possible": - -:::figure -![](/docs/deployments/azure/cloud-services/vip-swap.png "width=500") -::: - -With this setting enabled Octopus will attempt to swap the staging and production slots but, in the example above, it is always deploying to the staging slot. In order to perform a VIP swap we want to first deploy to Staging and then Production. In order to do this in Octopus, edit the Cloud Service process and replace the Slot setting with a variable that resolves the environment name. Press the square to the right of the Slot field to enable variable binding and enter `#{Octopus.Environment.Name}`: - -:::figure -![](/docs/deployments/azure/cloud-services/vip-swap-binding.png "width=500") -::: - -## Performing a VIP swap - -In order to perform a VIP swap you must have a deployment in your Cloud Service production slot. The first time you create a release and deploy it to Staging and then Production it will not VIP swap. On subsequent deployments to Staging and then Production a VIP swap will occur: - -:::figure -![](/docs/deployments/azure/cloud-services/vip-task-log.png "width=500") -::: - -## Automatic VIP swap \{#VIPSwap-AutomaticVIPswap} - -A production VIP swap can be automatically performed after a successful staging deployment through the use of lifecycles. A lifecycle should be configured with two phases: Staging and Production. The Staging phase contains the Staging environment and the Production phase contains the Production environment. The Production environment should be configured with "Deploy automatically to this environment as soon as the release enters this phase.": - -:::figure -![](/docs/deployments/azure/cloud-services/vip-lifecycles.png "width=500") -::: - -Configure the Cloud Service project to use the newly created lifecycle from the project process tab: - -:::figure -![](/docs/deployments/azure/cloud-services/vip-project-lifecycle.png "width=500") -::: - -Now each time a release is deployed to staging it will automatically perform a VIP swap with production. diff --git a/src/pages/docs/deployments/azure/deploying-a-package-to-an-azure-cloud-service/index.md b/src/pages/docs/deployments/azure/deploying-a-package-to-an-azure-cloud-service/index.md index c3e70aef17..9211fcbdaf 100644 --- a/src/pages/docs/deployments/azure/deploying-a-package-to-an-azure-cloud-service/index.md +++ b/src/pages/docs/deployments/azure/deploying-a-package-to-an-azure-cloud-service/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Redirect.astro title: Redirect -redirect: https://octopus.com/docs/deployments/azure/cloud-services +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure pubDate: 2023-01-01 navSearch: false navSitemap: false diff --git a/src/pages/docs/deployments/custom-scripts/run-a-script-step.md b/src/pages/docs/deployments/custom-scripts/run-a-script-step.md index 746e83890e..83f5a52572 100644 --- a/src/pages/docs/deployments/custom-scripts/run-a-script-step.md +++ b/src/pages/docs/deployments/custom-scripts/run-a-script-step.md @@ -147,6 +147,17 @@ If the package reference was _not_ configured to be extracted, then the un-extra These locations were designed to be convenient for use from custom scripts, as the relative path can be predicted, e.g. `./Acme` or `./Acme.zip`. If the absolute path is required the variables above may be used. +#### Docker image package variables +In the scenario where your package reference is a Docker image some additional variables will be contributed. These variables are (assuming a package-reference named `Acme`): + +| Variable name and description | Example | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------| +| `Octopus.Action.Package[Acme].Image`
The fully qualified image name | *index.docker.io/Acme:1.4.0* | +| `Octopus.Action.Package[Acme].Registry`
The URI of the registry from the feed where the image was acquired from | *index.docker.io* | +| `Octopus.Action.Package[Acme].Version`
The version of the image included in the release | *1.4.0* | +| `Octopus.Action.Package[Acme].Feed.UserName`
The username from the feed where the image was acquired from (if the feed is configured to use credentials) | *Alice* | +| `Octopus.Action.Package[Acme].Feed.Password`
The password from the feed where the image was acquired from (if the feed is configured to use credentials) | *Password01!* | + ## Older versions Scripts sourced from your Projects Git Repository was added in Octopus **2024.1**. In Octopus versions prior, the Git Repository source is not available. diff --git a/src/pages/docs/deployments/terraform/index.md b/src/pages/docs/deployments/terraform/index.md index 927df27df7..f1974bc998 100644 --- a/src/pages/docs/deployments/terraform/index.md +++ b/src/pages/docs/deployments/terraform/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2024-12-23 title: Terraform description: Terraform deployments navOrder: 100 @@ -16,7 +16,7 @@ Octopus Deploy provides first-class support for deploying Terraform templates. The `Plan to apply a Terraform template` will generate a plan for the result of running `apply` on a template, while `Plan a Terraform destroy` will generate a plan for the result of running `destroy` on the template. -Similarly, the `Apply a Terraform template` step can be used to create or update a resources from a Terraform template, while the `Destroy Terraform resources` step can be used to destroy existing Terraform resources. +Similarly, the `Apply a Terraform template` step can be used to create or update resources from a Terraform template, while the `Destroy Terraform resources` step can be used to destroy existing Terraform resources. The built-in Octopus Terraform steps are created to help you follow a pipeline using the following process: @@ -31,12 +31,12 @@ The built-in Octopus Terraform steps are created to help you follow a pipeline u All Terraform steps execute on a worker. By default, that will be the built-in worker in the Octopus Server. Learn about [workers](/docs/infrastructure/workers) and the different configuration options. :::div{.warning} -If the Terraform tool is updated above version `0.11`, you are using an Octopus version prior to **2020.5.0**, and you are using the **Source Code** option within a Terraform step, you will receive syntax warnings within Octopus. You can update the Terraform tool to a version higher than `0.11` without issue in an Octopus version prior to **2020.5.0** only if you use the **File inside a package** option within the terraform step. +If the Terraform tool is updated above version `0.11`, you are using an Octopus version prior to **2020.5.0**, and you are using the **Source Code** option within a Terraform step, you will receive syntax warnings within Octopus. You can update the Terraform tool to a version higher than `0.11` without issue in an Octopus version prior to **2020.5.0** only if you use the **File inside a package** option within the Terraform step. ::: ## Special variables -Setting the variable `Octopus.Action.Terraform.CustomTerraformExecutable` to the absolute path of a custom Terraform executable will result in the step using that executable instead of the one shipped with Octopus. You can use this variable to force the Terraform steps to use a specific version of Terraform, or to use the x64 version if you wish. +Setting the variable `Octopus.Action.Terraform.CustomTerraformExecutable` to the absolute path of a custom Terraform executable will result in the step using that executable instead of the one shipped with Octopus. You can use this variable to force the Terraform steps to use a specific version of Terraform or to use the x64 version if you wish. For example, setting `Octopus.Action.Terraform.CustomTerraformExecutable` to `C:\Apps\terraform.exe` will cause the steps to execute `C:\Apps\terraform.exe` rather than the built in copy of Terraform. @@ -48,7 +48,7 @@ The Terraform steps have some unique messages that may be displayed in the outpu ### Terraform-Configuration-UntestedTerraformCLIVersion -The Terraform steps in Octopus Deploy are tested against a range of versions of the Terraform CLI from 0.11.15 to 1.0.0. As new versions of Terraform are released, testing will be expanded to include these versions to ensure that they are compatible with the Terraform steps in Octopus. In the meantime, if the Terraform CLI version used in a step is outside the tested range a message will be displayed in the output indicating this. The Terraform step will likely continue to run successfully even if the CLI version being used has not been tested in Octopus. If the step succeeds, then the message will be informational only, and there is no action that needs to be taken. If the step resulted in an error, then the message will be a warning; however, the error may not be related to the version of Terraform being used. +The Terraform steps in Octopus Deploy are tested against a range of versions of the Terraform CLI. If the Terraform CLI version used in a step is outside the tested range, a message will be displayed in the output indicating this. The Terraform step will likely continue to run successfully even if the CLI version being used has not been tested in Octopus. If the step succeeds, then the message will be informational only, and there is no action that needs to be taken. If the step resulted in an error, then the message will be a warning; however, the error may not be related to the version of Terraform being used. ## Learn more diff --git a/src/pages/docs/infrastructure/azure-cloud-service-target.md b/src/pages/docs/infrastructure/azure-cloud-service-target.md index b3c23dd5b0..9211fcbdaf 100644 --- a/src/pages/docs/infrastructure/azure-cloud-service-target.md +++ b/src/pages/docs/infrastructure/azure-cloud-service-target.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Redirect.astro title: Redirect -redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure/cloud-service-targets +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure pubDate: 2023-01-01 navSearch: false navSitemap: false diff --git a/src/pages/docs/infrastructure/azure/cloud-service-targets/index.md b/src/pages/docs/infrastructure/azure/cloud-service-targets/index.md index b3c23dd5b0..9211fcbdaf 100644 --- a/src/pages/docs/infrastructure/azure/cloud-service-targets/index.md +++ b/src/pages/docs/infrastructure/azure/cloud-service-targets/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Redirect.astro title: Redirect -redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure/cloud-service-targets +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure pubDate: 2023-01-01 navSearch: false navSitemap: false diff --git a/src/pages/docs/infrastructure/deployment-targets/azure/cloud-service-targets/index.md b/src/pages/docs/infrastructure/deployment-targets/azure/cloud-service-targets/index.md index 378ea2b68c..b38f7ce103 100644 --- a/src/pages/docs/infrastructure/deployment-targets/azure/cloud-service-targets/index.md +++ b/src/pages/docs/infrastructure/deployment-targets/azure/cloud-service-targets/index.md @@ -1,55 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2024-06-27 -title: Azure Cloud Service targets -description: Azure Cloud Service deployment targets allow you to reference existing classic Cloud Services in your Azure subscription, that you can then reference by target tag during deployments. -navOrder: 100 ---- - -Azure Cloud Service deployment targets allow you to reference existing classic Cloud Services in your Azure subscription, that you can then reference by [target tag](/docs/infrastructure/deployment-targets/target-tags) during deployments. - -:::div{.warning} -Microsoft [announced](https://blogs.msdn.microsoft.com/appserviceteam/2018/03/12/deprecating-service-management-apis-support-for-azure-app-services/) that from June 30th 2018 they are retiring support for Azure Service Management API (which indicates Cloud Services). Microsoft stated that _"Cloud Services is similar to Service Fabric in degree of control versus ease of use, but it's now a legacy service and Service Fabric is recommended for new development"_ ([source](https://docs.microsoft.com/en-us/azure/app-service/choose-web-site-cloud-service-vm)). - -Support for this feature will be deprecated in Octopus Server from the `2024.1` release. -::: - -## Requirements - -You can read more about all the PaaS targets [in our blog](https://octopus.com/blog/paas-targets). - -- You will need an [Azure Management Certificate account](/docs/infrastructure/accounts/azure/#azure-management-certificate) that references your Azure subscription. - -- Once your Azure account is setup, you will then need an existing Azure Cloud Service (classic) setup within your Azure subscription. To learn more about App Services, the Azure team provide [useful documentation on App Services](https://docs.microsoft.com/en-us/azure/cloud-services/) that can help you get started. If you are dynamically creating the cloud services during your deployment, check our section about [creating Cloud Service targets by scripts using service messages](#creating-cloud-service-targets-by-scripts). - -## Creating Cloud Service targets - -Once you have a Cloud Service setup within your Azure subscription, you are then ready to map that to an Octopus deployment target. - -To create an Azure Cloud Service target within Octopus: - -- Go to **Infrastructure ➜ Deployment Targets ➜ Add Deployment Target**. -- Select **Azure Cloud Service** from the list of available targets and click _Next_. -- Fill out the necessary fields, being sure to provide a unique target tag that clearly identifies your Azure Cloud Service target. - -:::figure -![](/docs/infrastructure/deployment-targets/azure/cloud-service-targets/create-azure-cloud-service-target.png) -::: - -- After clicking _Save_, your deployment target will be added and go through a health check to ensure Octopus can connect to it. -- If all goes well, you should see your newly created target in your **Deployment Targets** list, with a status of _Healthy_. - -### Creating Cloud Service targets by scripts - -Azure Cloud Service targets can also be created via a PowerShell cmdlet within a Deployment Process, this can be especially handy if you are also creating the Azure Cloud Service via a script. - -See [Creating Resources by script](/docs/infrastructure/deployment-targets/dynamic-infrastructure) for more information on creating Azure Cloud Services via a script. - -## Deploying to Cloud Service targets - -See our [documentation about this topic](/docs/deployments/azure/cloud-services) - -## Troubleshooting - -If your Azure Cloud Service target is not completing a health check successfully, you may need to check that your Octopus Server can communicate with Azure. It may be worth checking that your Azure Account is able to complete a _Save and Test_ to ensure Octopus can communicate with Azure and the management certificate referenced by the account is valid. If your Octopus Server is behind a proxy or firewall, you will need to consult with your Systems Administrator to ensure it is able to communicate with Azure. +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure +pubDate: 2023-01-01 +navSearch: false +navSitemap: false +navMenu: false +--- \ No newline at end of file diff --git a/src/pages/docs/infrastructure/deployment-targets/azure/index.md b/src/pages/docs/infrastructure/deployment-targets/azure/index.md index 08fe4ec9fa..3b713dcfe5 100644 --- a/src/pages/docs/infrastructure/deployment-targets/azure/index.md +++ b/src/pages/docs/infrastructure/deployment-targets/azure/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-06-27 +modDate: 2024-12-12 title: Azure targets description: Configure your Azure infrastructure navOrder: 40 @@ -16,8 +16,11 @@ The currently supported Azure targets are: - [Azure Service Fabric Clusters](/docs/infrastructure/deployment-targets/azure/service-fabric-cluster-targets). - [Azure Web Apps](/docs/infrastructure/deployment-targets/azure/web-app-targets) (also works for Azure Functions). -- [Azure Cloud Services](/docs/infrastructure/deployment-targets/azure/cloud-service-targets). +- Azure Kubernetes Service via the [Kubernetes Agent](/docs/kubernetes/targets/kubernetes-agent) and [Kubernetes API](/docs/kubernetes/targets/kubernetes-api) deployment targets. +- Azure VM via [Tentacle using Desired State Configuration (DSC)](/docs/infrastructure/deployment-targets/tentacle/windows/azure-virtual-machines/via-an-arm-template-with-dsc). :::div{.warning} -Regarding Azure Cloud Services, Microsoft [announced](https://blogs.msdn.microsoft.com/appserviceteam/2018/03/12/deprecating-service-management-apis-support-for-azure-app-services/) that from June 30th 2018 they are retiring support for Azure Service Management API (which indicates Cloud Services). Microsoft stated that _"Cloud Services is similar to Service Fabric in degree of control versus ease of use, but it's now a legacy service and Service Fabric is recommended for new development"_ ([source](https://docs.microsoft.com/en-us/azure/app-service/choose-web-site-cloud-service-vm)). +Azure Cloud Services are no longer supported in Octopus Deploy as of `2025.1`. + +Microsoft has deprecated these Azure services, and as of October 1st 2024 shut down existing Cloud Service deployments. ([Source](https://learn.microsoft.com/en-us/azure/cloud-services/cloud-services-choose-me)) ::: diff --git a/src/pages/docs/infrastructure/deployment-targets/azure/web-app-targets/index.md b/src/pages/docs/infrastructure/deployment-targets/azure/web-app-targets/index.md index 567569a3b0..7b7a57415f 100644 --- a/src/pages/docs/infrastructure/deployment-targets/azure/web-app-targets/index.md +++ b/src/pages/docs/infrastructure/deployment-targets/azure/web-app-targets/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-06-27 +modDate: 2024-12-12 title: Azure Web App targets description: Azure Web App deployment targets allow you to reference existing Web Apps in your Azure subscription, that you can then reference by target tag during deployments. navOrder: 20 @@ -17,7 +17,7 @@ From version 2022.1 Octopus can discover Azure Web App targets using tags on you - You need an [Azure Service Principal account](/docs/infrastructure/accounts/azure/#azure-service-principal) that references your Azure subscription. -- Once your Azure account is setup, you need an existing Azure Web App / App Service setup within your Azure subscription. To learn more about App Services, see the [Azure App Services documentation](https://docs.microsoft.com/en-us/azure/app-service/) that can help you get started. If you are dynamically creating the web app during your deployment, check our section about [creating Web App targets by scripts using service messages](#creating-web-app-targets-by-scripts). +- Once your Azure account is setup, you need an existing Azure Web App / App Service setup within your Azure subscription. To learn more about App Services, see the [Azure App Services documentation](https://docs.microsoft.com/en-us/azure/app-service/) that can help you get started. If you are dynamically creating the web app during your deployment, check our section about [discovering web app targets](#discovering-web-app-targets) or [creating Web App targets by scripts using service messages](#creating-web-app-targets-by-scripts). ## Discovering web app targets @@ -47,8 +47,8 @@ Once you have an App Service configured within your Azure subscription, you are To create an Azure Web App target within Octopus: -- Navigate to **Infrastructure ➜ Deployment Target ➜ Add Deployment Target**. -- Select **Azure Web App** from the list of available targets and click _Next_. +- Navigate to **Deploy ➜ Infrastructure ➜ Deployment Targets ➜ Add Deployment Target**. +- Select **Azure tab** and then select **Azure Web App** from the list of available targets and click _Next_. - Fill out the necessary fields, being sure to provide a unique target tag (formerly target role) that clearly identifies your Azure Web App target. :::figure diff --git a/src/pages/docs/infrastructure/deployment-targets/dynamic-infrastructure/azure-cloud-service-target.md b/src/pages/docs/infrastructure/deployment-targets/dynamic-infrastructure/azure-cloud-service-target.md new file mode 100644 index 0000000000..b38f7ce103 --- /dev/null +++ b/src/pages/docs/infrastructure/deployment-targets/dynamic-infrastructure/azure-cloud-service-target.md @@ -0,0 +1,9 @@ +--- +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure +pubDate: 2023-01-01 +navSearch: false +navSitemap: false +navMenu: false +--- \ No newline at end of file diff --git a/src/pages/docs/infrastructure/deployment-targets/dynamic-infrastructure/azure-cloud-service-target.mdx b/src/pages/docs/infrastructure/deployment-targets/dynamic-infrastructure/azure-cloud-service-target.mdx deleted file mode 100644 index 1a53440521..0000000000 --- a/src/pages/docs/infrastructure/deployment-targets/dynamic-infrastructure/azure-cloud-service-target.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2024-06-27 -title: Create Azure Cloud Service target command -description: Cmdlet for creating an Azure Cloud Service target -navOrder: 40 ---- -import CreateDeploymentTargetsHint from 'src/shared-content/infrastructure/create-deployment-targets-hint.include.md'; - -## Azure Cloud Service - -Command: **_New-OctopusAzureCloudServiceTarget_** - -| Parameter | Value | -| ------------------------------------| --------------------------------------------------------------------------------------- | -| `-name` | Name for the Octopus deployment target | -| `-azureCloudServiceName` | Name of the Azure Cloud Service | -| `-azureStorageAccount` | Name of the Azure Storage Account | -| `-azureDeploymentSlot` | Deployment slot.
Options are `staging` (default), `production` | -| `-swap` | Swap staging to production, or just deploy.
Options are `swap` (default), `deploy` | -| `-instanceCount` | Use the current instance count from Azure, or use the value in the configuration file.
Options are `current` (default), `configuration` | -| `-octopusAccountIdOrName` | Name or Id of the Account Resource in Octopus. Must be a Management Certificate Account | -| `-octopusRoles` | Comma separated list of [target tags](/docs/infrastructure/deployment-targets/target-tags) to assign | -| `-updateIfExisting` | Will update an existing Cloud Service target with the same name, create if it doesn't exist | -| `-octopusDefaultWorkerPoolIdOrName` | Name or Id of the Worker Pool for the deployment target to use. (Optional). Added in 2020.6.0. | - -Example: -```powershell -# Using default options -New-OctopusAzureCloudServiceTarget -name "My Azure Cloud Service Target" ` - -azureCloudServiceName "CloudService1" ` - -azureStorageAccount "MyAzureCloudStorageAccount" ` - -octopusAccountIdOrName "Service Management Cert Account" ` - -octopusRoles "AzureCloudService" ` - -updateIfExisting - -# Overriding default values -New-OctopusAzureCloudServiceTarget -name "My Azure Cloud Service Target" ` - -azureCloudServiceName "CloudService1" ` - -azureStorageAccount "MyAzureCloudStorageAccount" ` - -azureDeploymentSlot "production" ` - -swap "deploy" ` - -instanceCount "configuration" ` - -octopusAccountIdOrName "Service Management Cert Account" ` - -octopusDefaultWorkerPoolIdOrName "Azure Worker Pool" ` - -octopusRoles "AzureCloudService" -``` - - \ No newline at end of file diff --git a/src/pages/docs/infrastructure/deployment-targets/linux/ssh-deployments.md b/src/pages/docs/infrastructure/deployment-targets/linux/ssh-deployments.md index c280046906..46cfa146c7 100644 --- a/src/pages/docs/infrastructure/deployment-targets/linux/ssh-deployments.md +++ b/src/pages/docs/infrastructure/deployment-targets/linux/ssh-deployments.md @@ -30,6 +30,8 @@ If you are writing a cross-platform script, be aware of the differences between **Bash (and other shell) variables** Octopus Deploy will log into the SSH target via a non-interactive shell. Because of this, startup files like `.bashrc` are not fully evaluated. If you are referencing bash variables `export`ed in these files, you should move them before the following common code block at the top of the file: +```bash + ```bash # If not running interactively, don't do anything case $- in @@ -38,6 +40,7 @@ case $- in esac ``` + This will ensure that they are evaluated on non-interactive logins. ::: @@ -49,6 +52,9 @@ Your script can use a [variable value](/docs/projects/variables) by invoking the You can also set an [output variable](/docs/projects/variables/output-variables): +```bash +set_octopusvariable RandomNumber 3 +``` ```bash set_octopusvariable RandomNumber 3 ``` @@ -77,11 +83,11 @@ By making all paths relative to the user's home directory, you can then theoreti ## Package acquisition -Leveraging Calamari means that the deployment can obtain the package via the same methods as a target running the Tentacle agent; either pushed from the server or directly from a NuGet repository. There is therefore no bottleneck in acquisition if there are multiple SSH endpoints all trying to retrieve the same package independently. +Leveraging Calamari means that the deployment can obtain the package via the same methods as a target running the Tentacle agent; either pushed from the server or directly from a supported [external repository](/docs/packaging-applications/package-repositories). There is therefore no bottleneck in acquisition if there are multiple SSH endpoints all trying to retrieve the same package independently. ## Calamari -Calamari is the tool Octopus uses to execute deployments on a remote computer. Before any processing is begun we do an initial check to ensure the available Calamari executable on the endpoint is up to date with the server. If not, we push up the latest Calamari package and then recommence the task. The Calamari package is sent as a `.tar.gz` so it can be extracted with minimal dependencies. This means the server needs to be able to un-tar that package, however, this should be available by default in most distros. +Calamari is the tool Octopus uses to execute deployments on a remote computer. Before any processing is begun we do an initial check to ensure the available Calamari executable on the endpoint is up to date with the server. If not, we push up the latest Calamari package and then recommence the task. The Calamari package is sent as a `.tar.gz` so it can be extracted with minimal dependencies. This means the server needs to be able to un-tar that package, however, this should be available by default in most distributions. ## Learn more diff --git a/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md b/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md index a4a3f9df07..db3f6ce06f 100644 --- a/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md +++ b/src/pages/docs/kubernetes/targets/kubernetes-agent/index.md @@ -74,12 +74,16 @@ The Kubernetes agent follows [semantic versioning](https://semver.org/), so a ma | Kubernetes agent | Octopus Server | Kubernetes cluster | | ---------------- | ------------------------ | -------------------- | | 1.0.0 - 1.16.1 | **2024.2.6580** or newer | **1.26** to **1.29** | -| 1.17.0 - 1.\*.\* | **2024.2.6580** or newer | **1.28** to **1.31** | +| 1.17.0 - 1.19.2 | **2024.2.6580** or newer | **1.27** to **1.30** | +| 1.20.0 - 1.\*.\* | **2024.2.6580** or newer | **1.28** to **1.31** | | 2.0.0 - 2.2.1 | **2024.2.9396** or newer | **1.26** to **1.29** | -| 2.3.0 - 2.\*.\* | **2024.2.9396** or newer | **1.28** to **1.31** | +| 2.3.0 - 2.8.2 | **2024.2.9396** or newer | **1.27** to **1.30** | +| 2.9.0 - 2.\*.\* | **2024.2.9396** or newer | **1.28** to **1.31** | Additionally, the Kubernetes agent only supports **Linux AMD64** and **Linux ARM64** Kubernetes nodes. +See our [support policy](/docs/kubernetes/targets/kubernetes-agent/supported-versions-policy) for more information. + ## Installing the Kubernetes agent The Kubernetes agent is installed using [Helm](https://helm.sh) via the [octopusdeploy/kubernetes-agent](https://hub.docker.com/r/octopusdeploy/kubernetes-agent) chart. diff --git a/src/pages/docs/kubernetes/targets/kubernetes-agent/supported-versions-policy.md b/src/pages/docs/kubernetes/targets/kubernetes-agent/supported-versions-policy.md new file mode 100644 index 0000000000..c85ed2f8df --- /dev/null +++ b/src/pages/docs/kubernetes/targets/kubernetes-agent/supported-versions-policy.md @@ -0,0 +1,26 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2024-12-11 +modDate: 2024-12-11 +title: Support Policy for Kubernetes Versions +navTitle: Supported Versions Policy +navSection: Kubernetes agent +description: Policy for which versions of Kubernetes are supported by the Kubernetes agent +navOrder: 100 +--- + +[The Kubernetes project](https://kubernetes.io/releases/version-skew-policy/#supported-versions) maintains release branches for the most recent three minor releases of Kubernetes. + +Octopus aims to follow this support policy as closely as makes sense. + +## Kubernetes Agent + +The Kubernetes agent uses the [Kubernetes C# client](https://github.com/kubernetes-client/csharp) to interact with the Kubernetes API, so we are bound to their release cadence. The Kubernetes agent will receive an update within **3 months** of a new major release of the Kubernetes C# client being released. + +If your use case requires the latest and greatest version of Kubernetes before we have released a new version, please [contact support](https://octopus.com/company/contact) to discuss options. + +### Support for older versions + +Each time the Kubernetes agent is updated to support a new version of Kubernetes, support for older versions will be dropped in line with the Kubernetes project's supported versions. Historically, the APIs in use have been stable and the Kubernetes agent has remained compatible with older version of Kubernetes, however we can make no guarantees of this in the future. + +We strongly recommend leaving automatic Kubernetes agent updates enabled and keeping your Kubernetes cluster up to date in line with the latest support version. If you must maintain support for older versions, you can configure how the Kubernetes agent is automatically updated with [machine policies](/docs/infrastructure/deployment-targets/machine-policies#configure-machine-updates). \ No newline at end of file diff --git a/src/pages/docs/octopus-rest-api/calamari.md b/src/pages/docs/octopus-rest-api/calamari.md index 7abcc24c00..f9fd752200 100644 --- a/src/pages/docs/octopus-rest-api/calamari.md +++ b/src/pages/docs/octopus-rest-api/calamari.md @@ -1,26 +1,12 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2024-12-11 title: Calamari -description: Calamari is the command-line tool invoked by Tentacle during a deployment. It knows how to extract and install NuGet packages, run the Deploy.ps1 etc. conventions, modify configuration files, and all the other things that happen during an deployment. navOrder: 70 +description: Calamari is the command-line tool invoked by Tentacle during a deployment. It knows how to deploy to Kubernetes, extract and install packages, run scripts and conventions, modify configuration files, and all the other things that happen during a deployment. --- -Prior to **Octopus 3.0**, Tentacles were responsible for performing deployment steps. Tentacles were *smart*. They knew how to transform configuration files, modify IIS, and much, much more. - -:::figure -![](/docs/octopus-rest-api/images/3278198.png) -::: - -There were a few cons to this architecture: - -- To add or modify features, a new version of the Tentacle service was required. And some folks have a *lot* of Tentacles. -- Deploying to a target which shouldn't require a Tentacle (e.g. an Azure WebSite), required that the deployment go via a Tentacle. -- This wouldn't support SSH targets. All SSH can do is to run commands and move files. All the logic and conventions for .NET configuration transforms, etc. would need to be pushed from the Octopus Server. - -And so the *communication channel* (Tentacle) was decoupled from the *deployment engine*: Calamari was born. - Calamari is an [open-source](https://github.com/OctopusDeploy/Calamari), console-application. It supports many commands, which are responsible for performing deployment-steps. For example: ```bash @@ -29,13 +15,15 @@ Calamari deploy-package --package MyPackage.nupkg --variables Variables.json Calamari has commands to support: +- Deploying to Kubernetes via Helm/Kustomize/Yaml. - Deploying NuGet packages. - Running scripts (PowerShell, ScriptCS, Bash, F#). -- Deploying packages to Azure targets (Cloud Services, WebApps). +- Deploying packages to Cloud services (WebApps, Functions etc.). - Various other deployment related activities. -Each deployment, if it is not already present, the latest version of the Calamari executable is pushed to wherever it needs to be. This may be to: +On each deployment, if it is not already present, the latest version of the Calamari executable is pushed to wherever it needs to be. This may be to: +- A Kubernetes Agent - A Tentacle. - Via SSH to a Linux machine. - A network-drive for Offline-Package-Drop targets. @@ -48,7 +36,7 @@ Deployments now proceed as follows: 3. The deployment target invokes Calamari to perform each deployment step. 4. Calamari performs the deployment step. -Now that Calamari is open-source, it might help answer any questions you had around what happens during a deployment. For example, did you ever wonder what order conventions run in when deploying a package? +Since Calamari is open-source, you can see the actions that are performed during a deployment. For example, did you ever wonder what order conventions run in when deploying a package? ```csharp var conventions = new List @@ -78,4 +66,4 @@ var conventions = new List }; ``` -Calamari is published under the Apache license, and we'll continue to work on it in the open. One of the benefits of this architecture is that you can [fork the project](https://github.com/OctopusDeploy/Calamari), make your own changes, and then tell your **Octopus 3.0** server to use your own Calamari package. +Calamari is published under the Apache license, you can find the source code [here](https://github.com/OctopusDeploy/Calamari). diff --git a/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md b/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md index dd25f059ce..18d37a68f4 100644 --- a/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md +++ b/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-09-12 +modDate: 2024-12-16 title: Create release description: Using the Octopus CLI to create releases. navOrder: 100 @@ -44,13 +44,6 @@ Release creation: an asterisk. An asterisk will be assumed for StepName, PackageID, or PackageName if they are omitted. - Can be specified multiple times. - --git-resource=VALUE [Optional] Git reference to use for a Git resource - in the release. Format: StepName:GitRef or - StepName:GitResourceName:GitRef. GitRef can be - replaced with an asterisk. An asterisk means - use the step-defined default branch. - Can be specified multiple times. --packagesFolder=VALUE [Optional] A folder containing NuGet packages from which we should get versions. --releaseNotes=VALUE [Optional] Release Notes for the new release. diff --git a/src/pages/docs/octopus-rest-api/octopus-cli/deploy-release.md b/src/pages/docs/octopus-rest-api/octopus-cli/deploy-release.md index 768f098f94..228ff18fa7 100644 --- a/src/pages/docs/octopus-rest-api/octopus-cli/deploy-release.md +++ b/src/pages/docs/octopus-rest-api/octopus-cli/deploy-release.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-06-25 +modDate: 2024-12-16 title: Deploy release description: Using the Octopus CLI to deploy releases. navOrder: 100 @@ -24,7 +24,7 @@ Deployment: --waitForDeployment [Optional] Whether to wait synchronously for deployment to finish. --deploymentTimeout=VALUE - [Optional] Specifies maximum time (time span + [Optional] Specifies maximum time (timespan format) that the console session will wait for the deployment to finish(default 00:10:00). This will not stop the deployment. Requires -- @@ -33,7 +33,7 @@ Deployment: the deployment timeout is reached (flag, default false). --deploymentCheckSleepCycle=VALUE - [Optional] Specifies how much time (time span + [Optional] Specifies how much time (timespan format) should elapse between deployment status checks (default 00:00:10). --guidedFailure=VALUE [Optional] Whether to use guided failure mode. diff --git a/src/pages/docs/security/authentication/googleapps-authentication.mdx b/src/pages/docs/security/authentication/googleapps-authentication.mdx index 8a0a634ef9..a6c3587e4f 100644 --- a/src/pages/docs/security/authentication/googleapps-authentication.mdx +++ b/src/pages/docs/security/authentication/googleapps-authentication.mdx @@ -1,14 +1,14 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2024-12-10 title: Google Workspace authentication -description: Octopus Deploy can use GOogle Workspace authentication to identify users. +description: Octopus Deploy can use Google Workspace authentication to identify users. navOrder: 15 --- import AdminUser from 'src/shared-content/installation/admin-user.include.md'; -To use Google Workspace authentication with Octopus Server, Google Workspace must be configured to trust Octopus - by setting it up as an app. This section covers the details on how to configure the app. +To use Google Workspace authentication with Octopus Server, Google Workspace must be configured to trust Octopus by setting it up as an app. This section covers the details of configuring the app. ## Configure Google Workspace @@ -23,22 +23,22 @@ Once you have an account, log in to [https://console.developers.google.com](http 3. Click the **Configure consent screen** button. 4. Select the User Type **Internal** and click **Create**. 5. Fill out the **App information**, including a descriptive **App name** such as Octopus Server or Octopus Cloud, and select an appropriate **User support email**. -6. Fill out the the **App logo** details, upload a logo to make it easy to identify the application. You can download the Octopus logo [here](https://octopus.com/images/company/Logo-Blue_140px_rgb.png "width=500"). +6. Fill out the **App logo** details and upload a logo to make it easy to identify the application. You can download the Octopus logo [here](https://octopus.com/images/company/Logo-Blue_140px_rgb.png). 7. Fill out the **App domain** information, providing `https://octopus.com` as the **Application home page**, `https://octopus.com/privacy` as the **Application privacy policy link** and `https://octopus.com/legal/customer-agreement` as the **Application Terms of Service link**. Add the Top Level Domain of your Octopus instance to the **Authorized domains** list. If you are setting Google Workspaces up for **Octopus Cloud** this will be `octopus.app` and `octopus.com`. 8. Fill out the **Developer contact information**. 9. Click **Save and continue**. 10. On the **Scopes** screen, click **Save and continue**. 11. Click **Back to dashboard** 12. Select **Credentials** tab and click **Create credentials**, selecting **Create Oauth client ID**. -13. Under **Application type**, select `Web application`, In the **Name** field enter `Octopus`, click **Add URI** and enter `https://octopus.example.com/api/users/authenticatedToken/GoogleApps` (replacing `https://octopus.example.com` with the url of your Octopus Server) to the **Authorized redirect URIs** and click **Create**. +13. Under **Application type**, select `Web application`, In the **Name** field enter `Octopus`, click **Add URI**, and enter `https://octopus.example.com/api/users/authenticatedToken/GoogleApps` (replacing `https://octopus.example.com` with the URL of your Octopus Server) to the **Authorized redirect URIs** and click **Create**. 14. Enter a **Name** for identification, e.g. Octopus. This is the name that will appear when the user is asked to allow access to their details. 15. Take note of the **Client ID** and **Client secret** from the `OAuth client created` modal. :::div{.hint} **Tips:** -- **Reply URLs are case-sensitive** - Be aware that the path in this URL after the domain name was **case sensitive** during our testing. -- **Not using SSL?** - We highly recommend using SSL, but we know its not always possible. You can use `http` if you do not have SSL enabled on your Octopus Server. Please beware of the security implications in accepting a security token over an insecure channel. -Octopus integrates with [Let's Encrypt](/docs/security/exposing-octopus/lets-encrypt-integration) making it easier to setup SSL on your Octopus Server. +- **Reply URLs are case-sensitive** - Be aware that the path in this URL after the domain name was **case-sensitive** during our testing. +- **Not using SSL?** We highly recommend using SSL, but we know it's not always possible. If you do not have SSL enabled on your Octopus Server, you can use `http`. Please beware of the security implications of accepting a security token over an insecure channel. +Octopus integrates with [Let's Encrypt](/docs/security/exposing-octopus/lets-encrypt-integration), making it easier to set up SSL on your Octopus Server. ::: ## Configure Octopus Server @@ -81,9 +81,9 @@ If you already have Octopus user accounts and you want to enable external authen We do our best to log warnings to your Octopus Server log whenever possible. If you are having difficulty configuring Octopus to authenticate with Google Workspace, be sure to check your [server logs](/docs/support/log-files) for warnings. -### Double and triple check your configuration +### Double and triple-check your configuration -Unfortunately security-related configuration is sensitive to everything. Make sure: +Unfortunately, security-related configuration is sensitive to everything. Make sure: - You don't have any typos or copy-paste errors. - Remember things are case-sensitive. @@ -95,9 +95,9 @@ You can see the OpenID Connect metadata by going to [https://accounts.google.com ### Inspect the contents of the security token -Perhaps the contents of the security token sent back by Google Workspace aren't exactly the way Octopus expected, especially certain claims which may be missing or named differently. This will usually result in the Google Workspace user incorrectly mapping to a different Octopus User than expected. The best way to diagnose this is to inspect the JSON Web Token (JWT) which is sent from Google Workspace to Octopus via your browser. To inspect the contents of your security token: +Perhaps the contents of the security token sent back by Google Workspace aren't exactly the way Octopus expected, especially certain claims that may be missing or named differently. This will usually result in the Google Workspace user incorrectly mapping to a different Octopus User than expected. The best way to diagnose this is to inspect the JSON Web Token (JWT) which is sent from Google Workspace to Octopus via your browser. To inspect the contents of your security token: -1. Open the Developer Tools of your browser and enable Network logging making sure the network logging is preserved across requests. +1. Open your browser's Developer Tools and enable Network logging, making sure the network logging is preserved across requests. 2. In Chrome Dev Tools this is called "Preserve Log": :::figure @@ -117,5 +117,5 @@ Perhaps the contents of the security token sent back by Google Workspace aren't ::: 5. Don't worry if jwt.io complains about the token signature, it doesn't support RS256 which is used by Google Workspace. -6. Octopus uses most of the data to validate the token, but primarily uses the `sub`, `email` and `name` claims. If these claims are not present you will likely see unexpected behavior. +6. Octopus uses most of the data to validate the token, but it primarily uses the `sub`, `email`, and `name` claims. If these claims are not present, you will likely see unexpected behavior. 7. If you are not able to figure out what is going wrong, please send a copy of the decoded payload to our [support team](https://octopus.com/support) and let them know what behavior you are experiencing. diff --git a/src/pages/docs/security/outbound-requests/index.md b/src/pages/docs/security/outbound-requests/index.md index 3ee90b60bd..83865ea7fb 100644 --- a/src/pages/docs/security/outbound-requests/index.md +++ b/src/pages/docs/security/outbound-requests/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2024-12-13 title: Outbound requests description: Traffic details of network requests made by Octopus and Tentacle, and what information is included when Octopus checks for updates. navOrder: 25 @@ -9,6 +9,7 @@ navOrder: 25 This page describes any outbound network requests made by Octopus and Tentacle, and what information is included when Octopus checks for updates. +## Outbound requests by Tentacle ## Outbound requests by Tentacle For security reasons, we minimize the number of outbound requests made by the Tentacle deployment agent. The only outbound requests you should see are for: @@ -20,6 +21,7 @@ For security reasons, we minimize the number of outbound requests made by the Te It's possible that scripts in your packages may make outbound requests; in this case you should take care when deploying packages created by a third party. +## Outbound requests by Octopus ## Outbound requests by Octopus The Octopus Server makes the following outbound requests: @@ -31,6 +33,7 @@ The Octopus Server makes the following outbound requests: 5. Checking for updated [built-in step templates](/docs/projects/built-in-step-templates) (if enabled). 6. Checking for updated [community contributed step templates](/docs/projects/community-step-templates) (if enabled). 7. Behavioral telemetry is sent to `https://telemetry.octopus.com` (if enabled). +8. Email address is sent to `https://experiences.octopus.com` via In-App messaging (if enabled). ### Built-in step templates @@ -43,6 +46,7 @@ From **Octopus 2022.1** some built-in step templates can be automatically update Our community contributed step template integration queries `library.octopus.com` for updates. +## What information is included when Octopus checks for updates? ## What information is included when Octopus checks for updates? By default, Octopus will periodically check for new releases. You can opt-out of checking for updates by navigating to **Configuration ➜ Settings ➜ Updates** in Octopus. @@ -73,3 +77,5 @@ In isolated/air-gapped scenarios without access to the internet, it may prove be - Via the CLI [configure command](/docs/octopus-rest-api/octopus.server.exe-command-line/configure): `Octopus.Server.exe configure --sendTelemetry=false` - Dynamic Extensions - Via the CLI [configure command](/docs/octopus-rest-api/octopus.server.exe-command-line/configure): `Octopus.Server.exe configure --dynamicExtensionsEnabled=false` +- In-App Messaging via Chameleon + - Please contact [support@octopus.com](mailto:support@octopus.com) for assistance disabling In-App Messaging diff --git a/src/shared-content/scripts/find-variable-usage-scripts.include.md b/src/shared-content/scripts/find-variable-usage-scripts.include.md index d5f6946db6..e73eb627fa 100644 --- a/src/shared-content/scripts/find-variable-usage-scripts.include.md +++ b/src/shared-content/scripts/find-variable-usage-scripts.include.md @@ -36,6 +36,81 @@ $space = (Invoke-RestMethod -Method Get -Uri "$octopusURL/api/spaces/all" -Heade Write-Host "Looking for usages of variable named $variableToFind in space: '$spaceName'" +# Function to process deployment steps +function Process-DeploymentSteps { + param( + $steps, + $project, + $gitRef = $null + ) + + $results = @() + # Loop through steps + foreach ($step in $steps) { + $props = $step | Get-Member | Where-Object { $_.MemberType -eq "NoteProperty" } + foreach ($prop in $props) { + $propName = $prop.Name + $json = $step.$propName | ConvertTo-Json -Compress -Depth 10 + if ($null -ne $json -and ($json -like "*$variableToFind*")) { + $result = [pscustomobject]@{ + Project = $project.Name + VariableSet = $null + MatchType = "Step" + Context = $step.Name + Property = $propName + AdditionalContext = $null + Link = "$octopusURL$($project.Links.Web)/deployments/process/steps?actionId=$($step.Actions[0].Id)" + } + + if ($gitRef) { + $result | Add-Member -MemberType NoteProperty -Name "GitRef" -Value $gitRef + } + + $results += $result + } + } + } + return $results +} + +# Function to process runbook steps +function Process-RunbookSteps { + param( + $steps, + $project, + $runbook, + $gitRef = $null + ) + + $results = @() + # Loop through steps + foreach ($step in $steps) { + $props = $step | Get-Member | Where-Object { $_.MemberType -eq "NoteProperty" } + foreach ($prop in $props) { + $propName = $prop.Name + $json = $step.$propName | ConvertTo-Json -Compress -Depth 10 + if ($null -ne $json -and ($json -like "*$variableToFind*")) { + $result = [pscustomobject]@{ + Project = $project.Name + VariableSet = $null + MatchType = "Runbook Step" + Context = $runbook.Name + Property = $propName + AdditionalContext = $step.Name + Link = "$octopusURL$($project.Links.Web)/operations/runbooks/$($runbook.Id)/process/$($runbook.RunbookProcessId)/steps?actionId=$($step.Actions[0].Id)" + } + + if ($gitRef) { + $result | Add-Member -MemberType NoteProperty -Name "GitRef" -Value $gitRef + } + + $results += $result + } + } + } + return $results +} + # Get all projects $projects = Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/projects/all" -Headers $header @@ -45,6 +120,20 @@ foreach ($project in $projects) { # Get project variables $projectVariableSet = Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/variables/$($project.VariableSetId)" -Headers $header + # Get all GitRefs for CaC project + if ($project.IsVersionControlled) { + $gitBranches = Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/projects/$($project.Id)/git/branches" -Headers $header + $gitTags = Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/projects/$($project.Id)/git/tags" -Headers $header + + $gitRefs = @() + foreach($branch in $gitBranches.Items) { + $gitRefs += $branch.CanonicalName + } + foreach($tag in $gitTags.Items) { + $gitRefs += $tag.CanonicalName + } + } + # Check to see if variable is named in project variables. $matchingNamedVariables = $projectVariableSet.Variables | Where-Object { $_.Name -ieq "$variableToFind" } if ($null -ne $matchingNamedVariables) { @@ -84,30 +173,23 @@ foreach ($project in $projects) { # Search Deployment process if enabled if ($searchDeploymentProcesses -eq $True) { - # Get project deployment process - $deploymentProcess = (Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/deploymentprocesses/$($project.DeploymentProcessId)" -Headers $header) - - # Loop through steps - foreach ($step in $deploymentProcess.Steps) { - $props = $step | Get-Member | Where-Object { $_.MemberType -eq "NoteProperty" } - foreach ($prop in $props) { - $propName = $prop.Name - $json = $step.$propName | ConvertTo-Json -Compress -Depth 10 - if ($null -ne $json -and ($json -like "*$variableToFind*")) { - $result = [pscustomobject]@{ - Project = $project.Name - VariableSet = $null - MatchType = "Step" - Context = $step.Name - Property = $propName - AdditionalContext = $null - Link = "$octopusURL$($project.Links.Web)/deployments/process/steps?actionId=$($step.Actions[0].Id)" - } - # Add and de-dupe later - $variableTracking += $result - } + if ($project.IsVersionControlled) { + # For CaC Projects, loop through GitRefs + foreach ($gitRef in $gitRefs) { + $escapedGitRef = [Uri]::EscapeDataString($gitRef) + $processUrl = "$octopusURL/api/$($space.Id)/projects/$($project.Id)/$($escapedGitRef)/deploymentprocesses" + # Get project deployment process + $deploymentProcess = (Invoke-RestMethod -Method Get -Uri $processUrl -Headers $header) + # Add and de-dupe later + $variableTracking += Process-DeploymentSteps -steps $deploymentProcess.Steps -project $project -gitRef $gitRef } } + else { + # Get project deployment process + $deploymentProcess = (Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/deploymentprocesses/$($project.DeploymentProcessId)" -Headers $header) + # Add and de-dupe later + $variableTracking += Process-DeploymentSteps -steps $deploymentProcess.Steps -project $project + } } # Search Runbook processes if enabled @@ -118,30 +200,23 @@ foreach ($project in $projects) { # Loop through each runbook foreach ($runbook in $runbooks.Items) { - # Get runbook process - $runbookProcess = (Invoke-RestMethod -Method Get -Uri "$octopusURL$($runbook.Links.RunbookProcesses)" -Headers $header) - - # Loop through steps - foreach ($step in $runbookProcess.Steps) { - $props = $step | Get-Member | Where-Object { $_.MemberType -eq "NoteProperty" } - foreach ($prop in $props) { - $propName = $prop.Name - $json = $step.$propName | ConvertTo-Json -Compress -Depth 10 - if ($null -ne $json -and ($json -like "*$variableToFind*")) { - $result = [pscustomobject]@{ - Project = $project.Name - VariableSet = $null - MatchType = "Runbook Step" - Context = $runbook.Name - Property = $propName - AdditionalContext = $step.Name - Link = "$octopusURL$($project.Links.Web)/operations/runbooks/$($runbook.Id)/process/$($runbook.RunbookProcessId)/steps?actionId=$($step.Actions[0].Id)" - } - # Add and de-dupe later - $variableTracking += $result - } + # For CaC Projects, loop through GitRefs + if ($project.IsVersionControlled) { + foreach ($gitRef in $gitRefs) { + $escapedGitRef = [Uri]::EscapeDataString($gitRef) + $processUrl = "$octopusURL/api/$($space.Id)/projects/$($project.Id)/$($escapedGitRef)/runbookprocesses/$($runbook.RunbookProcessId)" + # Get runbook process + $runbookProcess = (Invoke-RestMethod -Method Get -Uri $processUrl -Headers $header) + # Add and de-dupe later + $variableTracking += Process-RunbookSteps -steps $runbookProcess.Steps -project $project -runbook $runbook -gitRef $gitRef } } + else { + # Get runbook process + $runbookProcess = (Invoke-RestMethod -Method Get -Uri "$octopusURL$($runbook.Links.RunbookProcesses)" -Headers $header) + # Add and de-dupe later + $variableTracking += Process-RunbookSteps -steps $runbookProcess.Steps -project $project -runbook $runbook + } } } }