From d866b57933e8d5517daebc029bf9124b6be3a9d0 Mon Sep 17 00:00:00 2001 From: Huy Nguyen Date: Thu, 27 Aug 2026 16:28:51 +1000 Subject: [PATCH 1/2] Document that the cloud target discovery account is saved on discovered targets and used for their deployments and health checks. --- .../cloud-target-discovery/index.md | 30 +++++++++++++++---- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md b/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md index 4d4ab35e68..75c341e885 100644 --- a/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md +++ b/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-06-27 +modDate: 2026-08-27 title: Cloud Target Discovery description: Cloud resources can be discovered and registered as deployment targets by Octopus navOrder: 90 @@ -39,7 +39,7 @@ To discover Azure cloud resources, Octopus uses the following variables: | Name | Required | Description | | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | -| `Octopus.Azure.Account` | Y | An [Azure account](/docs/projects/variables/azure-account-variables) to use when discovering cloud targets | +| `Octopus.Azure.Account` | Y | An [Azure account](/docs/projects/variables/azure-account-variables) to use when discovering cloud targets. This account is also saved on each target it discovers, and is the account Octopus uses to deploy to that target and to run its health checks. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). | From **Octopus 2022.3**, Azure steps that support target discovery will allow you to configure the variables above from within the step configuration if they have not been configured within your project yet. @@ -65,6 +65,10 @@ To switch off cloud target discovery for Azure: Once the variable is removed, cloud target discovery will be switched off for Azure resources in this project. The **Azure** tile in the **Cloud Connections** section of your Azure deployment steps will show **Configure** again, indicating that cloud target discovery is no longer active. +:::div{.warning} +Switching off discovery does not change the targets it has already discovered. Each one keeps the account it was discovered with. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). +::: + ### AWS To discover AWS cloud resources, Octopus uses the following variables: @@ -72,7 +76,7 @@ To discover AWS cloud resources, Octopus uses the following variables: | Name | Required | Description | | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Octopus.Aws.Regions` | Y | A comma separated list of AWS regions to perform target discovery in. | -| `Octopus.Aws.Account` | N | An [AWS account](/docs/projects/variables/aws-account-variables) account to use when discovering cloud targets. If this is not set then credentials from the worker on which the step is run will be used. | +| `Octopus.Aws.Account` | N | An [AWS account](/docs/projects/variables/aws-account-variables) account to use when discovering cloud targets. If this is not set then credentials from the worker on which the step is run will be used. When set, this account is also saved on each target it discovers, and is the account Octopus uses to deploy to that target and to run its health checks. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). | | `Octopus.Aws.WorkerPool` | N | A [worker pool](/docs/projects/variables/worker-pool-variables) to use when discovering cloud targets. If this is not set then the worker pool from the step will be used. If this is set any discovered targets will have this set as their worker pool. | | `Octopus.Aws.AssumedRole.Arn` | N | The ARN of an IAM role to assume during the discovery of targets. See [Using IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) for more information on using and assuming roles. | | `Octopus.Aws.AssumedRole.SessionName` | N | The name of the session to use if assuming a role during discovery. If not set then an automatically generated name provided by AWS will be used. | @@ -107,6 +111,10 @@ To switch off cloud target discovery for AWS: Once the variables are removed, cloud target discovery will be switched off for AWS resources in this project. The **Amazon Web Services** tile in the **Cloud Connections** section of your AWS deployment steps will show **Configure** again, indicating that cloud target discovery is no longer active. +:::div{.warning} +Switching off discovery does not change the targets it has already discovered. Each one keeps the account it was discovered with. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). +::: + ## Tag cloud resources Octopus looks for tags applied to cloud resources to discover and create deployment targets for you. @@ -169,7 +177,7 @@ Cloud Target Discovery will often discover resources which already have targets ### Previously discovered targets -If a target has been created via Cloud Target Discovery, the next time the same cloud resource is discovered, the target will simply be updated. Existing targets are matched by target name, which is formatted depending on the discovered resource. The names are chosen to be unique but as readable as possible. +If a target has been created via Cloud Target Discovery, the next time the same cloud resource is discovered, the target will simply be updated. The update replaces the target's connection details, including its account, with the values from the new discovery run. Existing targets are matched by target name, which is formatted depending on the discovered resource. The names are chosen to be unique but as readable as possible. - Azure Web App: `azure-web-app/{resource-group}/{web-app-name}` - ECS Cluster: `{ecs-cluster-arn}` @@ -177,11 +185,23 @@ If a target has been created via Cloud Target Discovery, the next time the same - EKS Cluster: `{eks-cluster-arn}` :::div{.warning} -Renaming or moving cloud resources can cause target discovery to create duplicate targets. In most cases the old target will become unhealthy and be removed automatically by Octopus (see [Cleaning up unhealthy targets]) but in some cases the old target may still be healthy. In these cases, it must be removed manually. +Renaming or moving cloud resources can cause target discovery to create duplicate targets. In most cases the old target will become unhealthy and be removed automatically by Octopus (see [Cleaning up unhealthy targets](#cleaning-up-unhealthy-targets)) but in some cases the old target may still be healthy. In these cases, it must be removed manually. Automatic removal only happens when a target fails its health checks; it is not triggered by a discovery run that no longer reports the resource. **Example:** If you move an AKS Cluster to a different subscription and then update your Account in Octopus to use the new subscription ID, the old target will still pass its health-check. When discovery occurs a new target will be created (with the new Subscription ID in the target name) and the old target will need to be removed manually. ::: +### Changing or removing the discovery account + +The account used for discovery is saved on every target it discovers. That account is what Octopus uses to deploy to the target and to run its health checks, so it stays on the target until another discovery run replaces it. + +This has a few consequences: + +- Changing the discovery account and deploying again will update the targets that discovery finds on that run, because the account is not part of the target name. +- Removing the discovery account switches discovery off, so nothing updates the existing targets. They keep the old account until you change them yourself. +- A target that references an account appears on that account's **Usage** tab, and will prevent that account from being deleted. + +To move a target off an account, go to **Infrastructure ➜ Deployment Targets**, edit the target and select a different account. You can also delete the target, which is safe if discovery will run again and recreate it. + ### Overwriting manually added targets Manually added targets can be overridden by Cloud Target Discovery but this will only happen if they match the name format above exactly. If they are different, a new target will be created. From 572aa9cc20430c98cce21288bfc50b8e4c698842 Mon Sep 17 00:00:00 2001 From: Huy Nguyen Date: Fri, 28 Aug 2026 08:42:10 +1000 Subject: [PATCH 2/2] Move the account note out of the variable tables so the table columns stay aligned. --- .../deployment-targets/cloud-target-discovery/index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md b/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md index 75c341e885..37ab52e8f9 100644 --- a/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md +++ b/src/pages/docs/infrastructure/deployment-targets/cloud-target-discovery/index.md @@ -39,7 +39,9 @@ To discover Azure cloud resources, Octopus uses the following variables: | Name | Required | Description | | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | -| `Octopus.Azure.Account` | Y | An [Azure account](/docs/projects/variables/azure-account-variables) to use when discovering cloud targets. This account is also saved on each target it discovers, and is the account Octopus uses to deploy to that target and to run its health checks. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). | +| `Octopus.Azure.Account` | Y | An [Azure account](/docs/projects/variables/azure-account-variables) to use when discovering cloud targets | + +The account you set here is also saved on each target discovery creates, and is the account Octopus uses to deploy to that target and to run its health checks. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). From **Octopus 2022.3**, Azure steps that support target discovery will allow you to configure the variables above from within the step configuration if they have not been configured within your project yet. @@ -76,13 +78,15 @@ To discover AWS cloud resources, Octopus uses the following variables: | Name | Required | Description | | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Octopus.Aws.Regions` | Y | A comma separated list of AWS regions to perform target discovery in. | -| `Octopus.Aws.Account` | N | An [AWS account](/docs/projects/variables/aws-account-variables) account to use when discovering cloud targets. If this is not set then credentials from the worker on which the step is run will be used. When set, this account is also saved on each target it discovers, and is the account Octopus uses to deploy to that target and to run its health checks. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). | +| `Octopus.Aws.Account` | N | An [AWS account](/docs/projects/variables/aws-account-variables) account to use when discovering cloud targets. If this is not set then credentials from the worker on which the step is run will be used. | | `Octopus.Aws.WorkerPool` | N | A [worker pool](/docs/projects/variables/worker-pool-variables) to use when discovering cloud targets. If this is not set then the worker pool from the step will be used. If this is set any discovered targets will have this set as their worker pool. | | `Octopus.Aws.AssumedRole.Arn` | N | The ARN of an IAM role to assume during the discovery of targets. See [Using IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) for more information on using and assuming roles. | | `Octopus.Aws.AssumedRole.SessionName` | N | The name of the session to use if assuming a role during discovery. If not set then an automatically generated name provided by AWS will be used. | | `Octopus.Aws.AssumedRole.SessionDuration` | N | The maximum duration the session will be available for if assuming a role during discovery. If not set then the default duration from the IAM role will be used. | | `Octopus.Aws.AssumedRole.ExternalId` | N | An external ID to use if assuming a role during discovery. See the AWS documentation for more information on the use of external IDs. | +If you set `Octopus.Aws.Account`, that account is also saved on each target discovery creates, and is the account Octopus uses to deploy to that target and to run its health checks. See [changing or removing the discovery account](#changing-or-removing-the-discovery-account). + From **Octopus 2022.3**, AWS steps that support target discovery will allow you to configure the variables above from within the step configuration if they have not been configured within your project yet: 1. Open the deployment process and navigate to the AWS step