diff --git a/public/docs/projects/dashboard/project-dashboard-channels.jpeg b/public/docs/projects/dashboard/project-dashboard-channels.jpeg new file mode 100644 index 0000000000..be1bdb3180 Binary files /dev/null and b/public/docs/projects/dashboard/project-dashboard-channels.jpeg differ diff --git a/public/docs/projects/dashboard/project-dashboard-default.jpeg b/public/docs/projects/dashboard/project-dashboard-default.jpeg new file mode 100644 index 0000000000..df077e9480 Binary files /dev/null and b/public/docs/projects/dashboard/project-dashboard-default.jpeg differ diff --git a/public/docs/projects/dashboard/project-dashboard-tenants.jpeg b/public/docs/projects/dashboard/project-dashboard-tenants.jpeg new file mode 100644 index 0000000000..5aad28d0c2 Binary files /dev/null and b/public/docs/projects/dashboard/project-dashboard-tenants.jpeg differ diff --git a/src/pages/docs/administration/retention-policies/index.mdx b/src/pages/docs/administration/retention-policies/index.mdx index 24836b158c..ef2ef98970 100644 --- a/src/pages/docs/administration/retention-policies/index.mdx +++ b/src/pages/docs/administration/retention-policies/index.mdx @@ -1,16 +1,17 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-03-12 +modDate: 2025-04-22 title: Retention policies icon: fa-solid fa-broom description: Retention policies allow you to specify the releases, packages and files you want to keep as well as the ones you want cleaned up. navOrder: 70 hideInThisSectionHeader: true --- + import OctopusCloudStorageLimits from 'src/shared-content/octopus-cloud/octopus-cloud-storage-limits-hint.include.md'; -As you deploy more often and to different environments, files and releases can build up. Octopus handles this using retention policies. They allow you to control how Octopus decides which releases, packages and files are kept. +As you deploy more often and to different environments, files and releases can build up. Octopus handles this using retention policies. They allow you to control how Octopus decides which releases, packages and files are kept. ## What is deleted \{#what-is-deleted} @@ -22,9 +23,9 @@ The Octopus Server settings delete **releases** from the database. This is a dat #### Releases included on a dashboard -One important thing to note about the release retention policy is that any releases displayed on either the main dashboard or a project dashboard are **never deleted**. This is true even if it matches a retention policy rule. +One important thing to note about the release retention policy is that any releases displayed on either the main dashboard or a [project dashboard](/docs/projects/project-dashboard) are **never deleted**. This is true even if it matches a retention policy rule. -These releases are assumed to be a working release and may still be promoted (even if their dates fall well outside the retention policy). This can be helpful as it means you don't have to worry about a recent release in the Staging environment being deleted before it can be promoted to Production. +These releases are assumed to be a working release and may still be promoted (even if their dates fall well outside the retention policy). This can be helpful as it means you don't have to worry about a recent release in the Staging environment being deleted before it can be promoted to Production. :::div{.hint} If you see a release that isn't being cleaned up, check the dashboards to see if it's being displayed. @@ -47,7 +48,6 @@ Workers also clean up any files and folders older than 90 days. Note that if you use the [Custom Installation Directory](/docs/projects/steps/configuration-features/custom-installation-directory) feature, we will never delete from that directory during retention policies as it's assumed this directory has a working release in it. This can be purged during deployment in the project step settings. - #### Packages Packages that are transferred during the deployment are managed based on free disk space. For each deployment, prior to acquiring the package, the free disk space is checked and if less than 20% it will delete the “least used” package(s) from the Tentacle file store location. Packages that gets removed will be reacquired if needed for another deployment. @@ -55,13 +55,14 @@ The disk space calculation for both targets and workers looks at the entire disk ### Built-in repository \{#built-in-repo-whats-deleted} -A retention policy can be applied to packages in the built-in Octopus package repository. By default, the policy is set to keep all packages indefinitely. This policy is *separate* from the [release retention policy](#releases-whats-deleted) described above. +A retention policy can be applied to packages in the built-in Octopus package repository. By default, the policy is set to keep all packages indefinitely. This policy is _separate_ from the [release retention policy](#releases-whats-deleted) described above. :::figure -![](/docs/administration/retention-policies/images/built-in-repository.png "width=500") +![](/docs/administration/retention-policies/images/built-in-repository.png 'width=500') ::: -When a package retention policy is applied, Octopus will delete packages that meet *both* of the following criteria: +When a package retention policy is applied, Octopus will delete packages that meet _both_ of the following criteria: + 1. The time span from the package's initial publish date exceeds the configured time period in the policy 2. The package is **not associated with any releases in Octopus**. @@ -72,6 +73,7 @@ When configuring the repository retention policy, it's also worth making note of ### Build information \{#build-information-whats-deleted} [Build information](/docs/packaging-applications/build-servers/build-information) stored in Octopus is associated with **packages**. Octopus will decide how long to keep the build information based on the package they are linked to: + - If the package is used by a release, it will be kept. - If the package is present in the built-in repository, and a package retention policy has been configured, then the record will be kept according to that value. If no package retention policy has been configured, then the build information record will be kept indefinitely. - If the package is not present in the built-in repository, it's assumed that the package belongs to an [external package repository](/docs/packaging-applications/package-repositories). The build information record will be kept for a fixed value of 100 days from when it was published to Octopus. @@ -81,9 +83,10 @@ When configuring the repository retention policy, it's also worth making note of [Tasks](/docs/tasks) stored in Octopus are kept based on their time of completion. Octopus will retain: - - All incomplete tasks. - - The 20 most recently completed task per type. - - The 20,000 most recently completed task per type within the last 30 days. + +- All incomplete tasks. +- The 20 most recently completed task per type. +- The 20,000 most recently completed task per type within the last 30 days. ## What isn't deleted \{#what-is-not-deleted} @@ -108,10 +111,10 @@ If you have a release retention policy for a project that has a final phase of k In this section we walk through what's deleted for an example project when the retention policy task runs. Consider a project that has the following lifecycle defined: :::figure -![Release retention task example lifecycle](/docs/administration/retention-policies/images/retention-lifecycle-example.png "width=500") +![Release retention task example lifecycle](/docs/administration/retention-policies/images/retention-lifecycle-example.png 'width=500') ::: -It contains two phases, both are set to keep the last 3 releases. +It contains two phases, both are set to keep the last 3 releases. The project has 15 releases, of which: @@ -119,11 +122,12 @@ The project has 15 releases, of which: - `0.0.7` through `0.0.9` are deployed to Staging. - `0.0.1` through `0.0.6` are deployed to both Staging and Production. -When the retention policy runs for this lifecycle, it keeps a count of both **undeployed releases** it finds, as well as a separate count for **releases per phase**. +When the retention policy runs for this lifecycle, it keeps a count of both **undeployed releases** it finds, as well as a separate count for **releases per phase**. For a release to be deleted, the count must be greater than the required number for each phase the release has been deployed to. In this example, release `0.0.2` is the fourth release kept for Staging, but only the third for Production, so it will be kept. Each phase defined in this lifecycle will keep a maximum of **5 releases**: + - 1 release for the current dashboard version. - 1 release for the dashboard version's rollback. - The last 3 releases, as configured in the phase. @@ -164,16 +168,16 @@ Undeployed releases will simply keep the number we have selected and no more. Wh Under **Deploy ➜ Lifecycles** you select the Lifecycle you want to define or edit your retention policy for: :::figure -![](/docs/administration/retention-policies/images/lifecycles.png "width=500") +![](/docs/administration/retention-policies/images/lifecycles.png 'width=500') ::: Each phase will inherit the retention policy from the above phase, but this is something you can change by expanding the Retention Policy panel. :::figure -![](/docs/administration/retention-policies/images/lifecycle-retention-policy.png "width=500") +![](/docs/administration/retention-policies/images/lifecycle-retention-policy.png 'width=500') ::: -*Releases* determines what is kept on the Octopus Server, and *Files on Tentacle* determines what files are kept on the Tentacle. +_Releases_ determines what is kept on the Octopus Server, and _Files on Tentacle_ determines what files are kept on the Tentacle. In Octopus Server, you can keep all, or select a number of releases to keep. @@ -184,15 +188,17 @@ Alternatively, you can specify a number of days worth of releases and files to k ### Inherited retention policies As mentioned above, any phase that does not have a retention policy set will inherit its retention policy in the following priority: + 1. From the latest previous phase with a custom retention policy 2. From the lifecycle retention policy This can be observed in the following retention policy setup: -* Lifecycle: Keep 3 Releases -* Phase 1 (Dev): Inherit (Keep 3 Releases) -* Phase 2 (Test): Inherit (Keep 3 Releases) -* Phase 3 (Staging): Keep 5 Releases -* Phase 4 (Prod): Inherit (Keep 5 Releases) + +- Lifecycle: Keep 3 Releases +- Phase 1 (Dev): Inherit (Keep 3 Releases) +- Phase 2 (Test): Inherit (Keep 3 Releases) +- Phase 3 (Staging): Keep 5 Releases +- Phase 4 (Prod): Inherit (Keep 5 Releases) Note how Dev and Test inherit their policies from the lifecycle retention policy as there is no previous phase with a custom retention policy. As Prod comes after Staging, a phase which has a custom retention policy, Prod inherits its retention policy from Staging instead. @@ -203,7 +209,7 @@ Phases prioritize retention policies from the latest previous phase over the lif You can find the built-in repository retention policy settings under **Deploy ➜ Packages**. :::figure -![](/docs/administration/retention-policies/images/built-in-feed-retention-policy.png "width=500") +![](/docs/administration/retention-policies/images/built-in-feed-retention-policy.png 'width=500') ::: In Octopus Server, this can be set to keep packages forever, or for a set number of days. @@ -211,10 +217,10 @@ In Octopus Server, this can be set to keep packages forever, or for a set number :::figure -![](/docs/administration/retention-policies/images/built-in-repository.png "width=500") +![](/docs/administration/retention-policies/images/built-in-repository.png 'width=500') ::: -Choosing *A limited time* will allow you to select the number of days to keep a package in the repository. The default value is 30, but you can choose something shorter or longer based on your needs. +Choosing _A limited time_ will allow you to select the number of days to keep a package in the repository. The default value is 30, but you can choose something shorter or longer based on your needs. :::div{.hint} **Note on package clean-up** @@ -230,13 +236,13 @@ Octopus does not apply any retention policies to external feeds. However the pac Whether you have an existing Octopus Server or are setting it up for the first time, we have some recommendations when setting retention policies. -### Change the defaults +### Change the defaults -Octopus comes with default retention policies to keep everything, forever. If you have small packages or don't release frequently, you may never notice any adverse effects. As your usage grows, you might run into disk space or performance issues as Octopus continues to store everything. +Octopus comes with default retention policies to keep everything, forever. If you have small packages or don't release frequently, you may never notice any adverse effects. As your usage grows, you might run into disk space or performance issues as Octopus continues to store everything. We recommend changing the default values on the different retention policies available in Octopus. -For releases, you have the choice to clean up after a specified number of releases or a specified number of days. If you're not sure what value to pick, we recommend keeping the last three releases for both releases and the extracted packages. +For releases, you have the choice to clean up after a specified number of releases or a specified number of days. If you're not sure what value to pick, we recommend keeping the last three releases for both releases and the extracted packages. Remember, if you have multiple lifecycles then we recommend configuring the retention policies on each lifecycle and any defined phases. diff --git a/src/pages/docs/best-practices/deployments/releases-and-deployments.md b/src/pages/docs/best-practices/deployments/releases-and-deployments.md index a32ffe8a9c..e0b4411ce9 100644 --- a/src/pages/docs/best-practices/deployments/releases-and-deployments.md +++ b/src/pages/docs/best-practices/deployments/releases-and-deployments.md @@ -8,12 +8,12 @@ navOrder: 95 hideInThisSection: true --- -[Releases](/docs/releases/) are snapshots of your deployment process and other associated assets (references to package versions, scripts, variables) as they existed when the release was created. A release is [deployed](/docs/deployments/) to [environments](/docs/infrastructure/environments), or different stages in your deployment pipeline. +[Releases](/docs/releases/) are snapshots of your deployment process and other associated assets (references to package versions, scripts, variables) as they existed when the release was created. A release is [deployed](/docs/deployments/) to [environments](/docs/infrastructure/environments), or different stages in your deployment pipeline. -A release snapshot takes references (rather than the entire resource) for certain items in a release. For example, the release references the package version, not the package itself. Take care when overwriting existing packages that may be used in releases or snapshots. +A release snapshot takes references (rather than the entire resource) for certain items in a release. For example, the release references the package version, not the package itself. Take care when overwriting existing packages that may be used in releases or snapshots. -:::div{.hint} -**Tenant variables** are not included in release snapshots. Find out more in our [tenant documentation](/docs/tenants/tenant-variables). +:::div{.hint} +**Tenant variables** are not included in release snapshots. Find out more in our [tenant documentation](/docs/tenants/tenant-variables). ::: ## Release creation @@ -25,7 +25,7 @@ When you create a release, you must enter or choose the following items: - The channel (only appears when a project has more than one channel). - Release notes (optional) -Let the CI, or Build Server, create the release after uploading the package you wish to deploy. The build server knows when it has finished uploading the package, along with other important information, such as the current branch, was the build triggered by a pull request, and more. +Let the CI, or Build Server, create the release after uploading the package you wish to deploy. The build server knows when it has finished uploading the package, along with other important information, such as the current branch, was the build triggered by a pull request, and more. :::div{.hint} Octopus Deploy provides [built-in package repository](/docs/projects/project-triggers/built-in-package-repository-triggers) and [external feed](/docs/projects/project-triggers/external-feed-triggers) triggers. These triggers will automatically create a release when a new package version is pushed. @@ -40,7 +40,7 @@ Release creation triggers have the following limitations: ## Updating a release -The release includes a snapshot containing the deployment process, variables (including Variable Sets), and package versions. +The release includes a snapshot containing the deployment process, variables (including Variable Sets), and package versions. You can update the following in a release: @@ -54,27 +54,27 @@ However, you cannot change the following in the release snapshot: - Channel - Deployment Process -Never to modify a release unless it is absolutely necessary. A release represents a snapshot in time, and it should be the same when deploying to the different stages or environments in your pipeline. Changing it after the fact can lead to unpredictable results. +Never to modify a release unless it is absolutely necessary. A release represents a snapshot in time, and it should be the same when deploying to the different stages or environments in your pipeline. Changing it after the fact can lead to unpredictable results. ## Deploying a release -A release is deployed to different stages or environments in your pipeline. Releases can be deployed 0 to N times before **production**. +A release is deployed to different stages or environments in your pipeline. Releases can be deployed 0 to N times before **production**. -A release must be deployed to at least **ONE** environment before deploying to **production**, even during an emergency or a production outage. Deploying to **production** should go from an "all hands on deck" event to a non-event. The release will have been tested at least once if not multiple times, in different stages in your pipeline by the time you deploy to **production**. By that point, most, if not all, surprises should have been found and fixed. +A release must be deployed to at least **ONE** environment before deploying to **production**, even during an emergency or a production outage. Deploying to **production** should go from an "all hands on deck" event to a non-event. The release will have been tested at least once if not multiple times, in different stages in your pipeline by the time you deploy to **production**. By that point, most, if not all, surprises should have been found and fixed. ## Blocking a release -During testing, you might find a show-stopping bug. Or the UI isn't acceptable to the business owner. There are several reasons for a release rejection to occur. +During testing, you might find a show-stopping bug. Or the UI isn't acceptable to the business owner. There are several reasons for a release rejection to occur. -Most rejections should occur in **development** or **test** environments before merging into the main branch. Assuming your lifecycles match your branching strategy, those releases would never make it to **production** because the lifecycle doesn't include it. +Most rejections should occur in **development** or **test** environments before merging into the main branch. Assuming your lifecycles match your branching strategy, those releases would never make it to **production** because the lifecycle doesn't include it. -When a release built from the main or a release branch is rejected, leverage the [prevent release progression](/docs/releases/prevent-release-progression) functionality to block that release from being deployed to additional stages or environments in your pipeline. +When a release built from the main or a release branch is rejected, leverage the [prevent release progression](/docs/releases/prevent-release-progression) functionality to block that release from being deployed to additional stages or environments in your pipeline. ## Release and Deployment retention -As stated earlier, creating a release snapshots the variables, deployment process, etc. Each deployment also has a snapshot of the variables and deployment process created. As you can imagine, all of these snapshots start to consume more and more space in the database. +As stated earlier, creating a release snapshots the variables, deployment process, etc. Each deployment also has a snapshot of the variables and deployment process created. As you can imagine, all of these snapshots start to consume more and more space in the database. -Our recommendation is to configure [retention policies](/docs/administration/retention-policies) to clean up old releases. Have a unique retention policy per environment. For example: +Our recommendation is to configure [retention policies](/docs/administration/retention-policies) to clean up old releases. Have a unique retention policy per environment. For example: - Development: keep the last one (1) release - Test: keep the last two (2) releases @@ -83,37 +83,37 @@ Our recommendation is to configure [retention policies](/docs/administration/ret Some notes about retention policies: -- No release appearing on either a project dashboard or the main dashboard will be deleted even if the release falls well outside of the dates for the retention policy. -- Octopus will always keep the current release and the most recent previous release in any lifecycle phase. Keeping the most recent release ensures you can quickly roll back in an emergency. -- The algorithm calculating the releases to delete is very conservative. It prefers to keep releases rather than delete them. +- No release appearing on either a [project dashboard](/docs/projects/project-dashboard) or the main dashboard will be deleted even if the release falls well outside of the dates for the retention policy. +- Octopus will always keep the current release and the most recent previous release in any lifecycle phase. Keeping the most recent release ensures you can quickly roll back in an emergency. +- The algorithm calculating the releases to delete is very conservative. It prefers to keep releases rather than delete them. :::div{.hint} -When the retention policies delete a release, it removes that release from the project (along with corresponding snapshots). Audit information about the release, who created it, when it was deployed, and so on is still retained and can be viewed in the [audit log](/docs/security/users-and-teams/auditing). +When the retention policies delete a release, it removes that release from the project (along with corresponding snapshots). Audit information about the release, who created it, when it was deployed, and so on is still retained and can be viewed in the [audit log](/docs/security/users-and-teams/auditing). ::: ## Free up deployment target disk space -As you deploy more frequently, the available disk space on your deployment targets will be reduced. That reduction will continue until you either run out of disk space or retention policies are configured. When you configure the retention policy in the lifecycle, you are presented with two options: +As you deploy more frequently, the available disk space on your deployment targets will be reduced. That reduction will continue until you either run out of disk space or retention policies are configured. When you configure the retention policy in the lifecycle, you are presented with two options: -- How long should we keep releases? That means how long the release is retained on the Octopus Server. -- How long should we keep extracted packages and files on disk on Tentacles? That means how long the release is retained on your deployment targets. +- How long should we keep releases? That means how long the release is retained on the Octopus Server. +- How long should we keep extracted packages and files on disk on Tentacles? That means how long the release is retained on your deployment targets. -Unless you are using a [custom install directory](/docs/projects/steps/configuration-features/custom-installation-directory), Octopus Deploy will create a unique folder on your deployment targets to extract packages to. The unique folder is generated _per deployment_. If the same release is deployed five times, expect to see five unique folders. +Unless you are using a [custom install directory](/docs/projects/steps/configuration-features/custom-installation-directory), Octopus Deploy will create a unique folder on your deployment targets to extract packages to. The unique folder is generated _per deployment_. If the same release is deployed five times, expect to see five unique folders. -Our recommendation is to configure your deployment target retention policies to match your release retention policies. Unless, of course, you are limited by disk space. If that happens, then set your deployment target retention policy to something smaller than the release retention policy. +Our recommendation is to configure your deployment target retention policies to match your release retention policies. Unless, of course, you are limited by disk space. If that happens, then set your deployment target retention policy to something smaller than the release retention policy. :::div{.hint} -Both retention policies follow the same rules. No release appearing on a dashboard will be deleted, nor will the current and previous release. +Both retention policies follow the same rules. No release appearing on a dashboard will be deleted, nor will the current and previous release. ::: -Retention policies are not applied to any package with a custom install directory configured. You are responsible for cleaning up the custom install directory. +Retention policies are not applied to any package with a custom install directory configured. You are responsible for cleaning up the custom install directory. ## Further reading For further reading on releases and deployments in Octopus Deploy please see: - [Releases](/docs/releases) -- [Deployments](/docs/deployments) +- [Deployments](/docs/deployments) - [Environments](/docs/infrastructure/environments) - [Lifecycles](/docs/releases/lifecycles) -- [Retention Policies](/docs/administration/retention-policies) \ No newline at end of file +- [Retention Policies](/docs/administration/retention-policies) diff --git a/src/pages/docs/deployments/patterns/elastic-and-transient-environments/keeping-deployment-targets-up-to-date.md b/src/pages/docs/deployments/patterns/elastic-and-transient-environments/keeping-deployment-targets-up-to-date.md index 507e4979ea..4aebca7b7a 100644 --- a/src/pages/docs/deployments/patterns/elastic-and-transient-environments/keeping-deployment-targets-up-to-date.md +++ b/src/pages/docs/deployments/patterns/elastic-and-transient-environments/keeping-deployment-targets-up-to-date.md @@ -7,15 +7,15 @@ description: Octopus can ensure that deployment targets are kept up to date with navOrder: 2 --- -Octopus Deploy can ensure that deployment targets are kept up to date with the relevant releases. This can be useful when [deploying to transient targets](/docs/deployments/patterns/elastic-and-transient-environments/deploying-to-transient-targets) or when new deployment targets are added to an environment. +Octopus Deploy can ensure that deployment targets are kept up to date with the relevant releases. This can be useful when [deploying to transient targets](/docs/deployments/patterns/elastic-and-transient-environments/deploying-to-transient-targets) or when new deployment targets are added to an environment. ## Triggers {#triggers} -Triggers are per-project settings that execute an action in response to an event. For this example we will create an automatic deployment trigger so that machines associated with the **TradingWebServer** [target tag](/docs/infrastructure/deployment-targets/#target-roles) are automatically kept up to date with the latest releases for OctoFX. Triggers can be found by selecting the *Triggers* menu item on the project screen. +Triggers are per-project settings that execute an action in response to an event. For this example we will create an automatic deployment trigger so that machines associated with the **TradingWebServer** [target tag](/docs/infrastructure/deployment-targets/#target-roles) are automatically kept up to date with the latest releases for OctoFX. Triggers can be found by selecting the _Triggers_ menu item on the project screen. ## Creating an automatic deployment trigger {#create-automatic-deployment-trigger} -1. Navigate to the project *Triggers* page. +1. Navigate to the project _Triggers_ page. 2. Create a new trigger by selecting **Create trigger**: :::figure @@ -23,7 +23,8 @@ Triggers are per-project settings that execute an action in response to an event ::: 3. Add events to the trigger. - - For **Octopus 3.6** and above, select the event group *"Machine becomes available for deployment"*. + +- For **Octopus 3.6** and above, select the event group _"Machine becomes available for deployment"_. 4. Select the environments (**Test A**) that this trigger applies to. @@ -37,7 +38,7 @@ Once the trigger has been created, it will ensure that any deployment targets ma ## Triggering an automatic deployment {#trigger-automatic-deployment} -To test the trigger, we will disable a deployment target, deploy to that target's environment and then re-enable the target. Octopus should automatically deploy the release to the target when it is re-enabled. +To test the trigger, we will disable a deployment target, deploy to that target's environment and then re-enable the target. Octopus should automatically deploy the release to the target when it is re-enabled. 1. Disable a target with the target tag **TradingWebServer** in the **Test A** environment: @@ -45,13 +46,13 @@ To test the trigger, we will disable a deployment target, deploy to that target' ![](/docs/deployments/patterns/elastic-and-transient-environments/images/5865573.png) ::: -2. Create a new release of OctoFX and deploy it to the **Test A** environment. It will skip the steps that have been scoped to the **TradingWebServer** target tag because no deployment targets are associated with that tag: +2. Create a new release of OctoFX and deploy it to the **Test A** environment. It will skip the steps that have been scoped to the **TradingWebServer** target tag because no deployment targets are associated with that tag: :::figure ![](/docs/deployments/patterns/elastic-and-transient-environments/images/5865574.png) ::: -3. Enable the deployment target **TAWeb01.** Octopus will automatically determine that it is missing the release we just deployed. The deployment is re-queued and will run only for the **TAWeb01** target, creating a new log section below the original deployment log: +3. Enable the deployment target **TAWeb01.** Octopus will automatically determine that it is missing the release we just deployed. The deployment is re-queued and will run only for the **TAWeb01** target, creating a new log section below the original deployment log: :::figure ![](/docs/deployments/patterns/elastic-and-transient-environments/images/5865575.png) @@ -59,7 +60,7 @@ To test the trigger, we will disable a deployment target, deploy to that target' ## Overriding the release used for automatic deployments {#override-release-for-automatic-deployments} -Automatic deployments attempts to calculate the release to use for a project and environment (using the *current* and *successful* release that has been deployed, as shown in your Project Overview dashboard). In some cases the calculated release may not be the release that should be automatically deployed, or Octopus may not be able to find a deployment for an environment (maybe you have a release, but have not yet deployed it anywhere). It is possible to explicitly set the release that should be automatically deployed by overriding the automatic-deployment-release. Overrides can be configured using the [Octopus CLI](/docs/octopus-rest-api/octopus-cli/) or through [Octopus.Client](/docs/octopus-rest-api/octopus.client). Overrides define a release for a project when deploying to an environment (this can, for example, be useful for cloud-testing-automation when standing up new cloud infrastructure). For multi-tenanted deployments, overrides may be configured for each environment/tenant combination. +Automatic deployments attempts to calculate the release to use for a project and environment (using the _current_ and _successful_ release that has been deployed, as shown in your Project Overview dashboard). In some cases the calculated release may not be the release that should be automatically deployed, or Octopus may not be able to find a deployment for an environment (maybe you have a release, but have not yet deployed it anywhere). It is possible to explicitly set the release that should be automatically deployed by overriding the automatic-deployment-release. Overrides can be configured using the [Octopus CLI](/docs/octopus-rest-api/octopus-cli/) or through [Octopus.Client](/docs/octopus-rest-api/octopus.client). Overrides define a release for a project when deploying to an environment (this can, for example, be useful for cloud-testing-automation when standing up new cloud infrastructure). For multi-tenanted deployments, overrides may be configured for each environment/tenant combination. **Octopus CLI** @@ -87,11 +88,11 @@ $project.AddAutoDeployReleaseOverride($environment, $release) $repository.Projects.Modify($project) ``` -Automatic deployment overrides are cleared when a deployment is performed to the same project/environment/tenant combination as the override. For example: if an override is set for version 1.2 of HelloWorld to the Test environment and version 1.3 of HelloWorld is deployed to the Test environment, the 1.2 override will be deleted. Release overrides will be cleared as soon as they have automated an actual deployment. +Automatic deployment overrides are cleared when a deployment is performed to the same project/environment/tenant combination as the override. For example: if an override is set for version 1.2 of HelloWorld to the Test environment and version 1.3 of HelloWorld is deployed to the Test environment, the 1.2 override will be deleted. Release overrides will be cleared as soon as they have automated an actual deployment. ## Troubleshooting automatic deployments {#troubleshoot-automatic-deployments} -Octopus will attempt to automatically deploy the current releases for the environments that are appropriate for a machine. The current release is the one that was most recently *successfully* deployed as shown on the project dashboard. If a release is deployed and it fails, the previous successful release will continue to be automatically deployed. Octopus will not attempt automatic deployments for a project/environment/tenant while a release is being deployed to that project/environment/tenant. Once the deployment finishes, Octopus will deploy to any machines that require the deployment. +Octopus will attempt to automatically deploy the current releases for the environments that are appropriate for a machine. The current release is the one that was most recently _successfully_ deployed as shown on the [project dashboard](/docs/projects/project-dashboard). If a release is deployed and it fails, the previous successful release will continue to be automatically deployed. Octopus will not attempt automatic deployments for a project/environment/tenant while a release is being deployed to that project/environment/tenant. Once the deployment finishes, Octopus will deploy to any machines that require the deployment. Troubleshoot automatic deployment by viewing the auto deploy logs from the diagnostics page in the configuration section or viewing the [Audit log](/docs/security/users-and-teams/auditing). @@ -108,4 +109,4 @@ With machines now being kept up to date automatically you may be interested in [ ## Learn more -- [Deployment patterns blog posts](https://octopus.com/blog/tag/Deployment%20Patterns). \ No newline at end of file +- [Deployment patterns blog posts](https://octopus.com/blog/tag/Deployment%20Patterns). diff --git a/src/pages/docs/projects/project-dashboard.md b/src/pages/docs/projects/project-dashboard.md new file mode 100644 index 0000000000..221f98a230 --- /dev/null +++ b/src/pages/docs/projects/project-dashboard.md @@ -0,0 +1,101 @@ +--- +layout: src/layouts/Default.astro +title: Project dashboard +icon: fa-solid fa-shapes +description: Understanding the different project dashboard views. +position: 20 +hideInThisSection: true +hideInThisSectionHeader: true +pubDate: 2025-04-17 +--- + +The project dashboard gives you an at-a-glance view of your project. You’ll see a cherry-picked **selection of your releases**. You’ll also see where and when they were deployed in your [environments](/docs/infrastructure/environments), [tenants](/docs/tenants/), and [channels](/docs/releases/channels). + +You’ll see one of the following **dashboard views**: + +- [Default view](#default-view) +- [Channels view](#channels-view) +- [Tenants view](#tenants-view) + +The view you see depends on whether you’ve **added channels** to your project and whether you **allow tenanted deployments** in your project. All views allow you to filter and group your deployments to suit your needs. + +## Default view + +This view is shown if: + +- You **haven’t** added channels to your project +- Your project settings **don’t** allow tenanted deployments + +You’ll see a selection of releases and how they are deployed into environments in your **project’s lifecycle**. + +From this view you can deploy releases, create releases, and filter by environments. + +:::figure +![Project dashboard default view](/docs/projects/dashboard/project-dashboard-default.jpeg) +::: + +### Which releases are shown in the default view? + +- For each **environment**: + - Your most recently deployed release (whether or not the deployment was successful) + - Your next most recently deployed and successful release +- In **addition** to the above: + - Up to three of your most recent undeployed releases (but only if they were created after you last deployed a new release) + +## Channels view + +This view is shown if: + +- You’ve **added a channel** to your project +- Your project settings **don’t** allow tenanted deployments + +You’ll see a selection of releases for each channel and how they are deployed into environments in each **channel’s lifecycle**. + +From this view you can deploy releases in your channels, create releases, and filter by environments. + +:::figure +![Project dashboard channels view](/docs/projects/dashboard/project-dashboard-channels.jpeg) +::: + +### Which releases are shown in the channels view? + +- For each **environment**: + - Your most recently deployed release, whether or not the deployment was successful + - Your next most recently deployed and successful release +- For each **channel**: + - Up to three of your most recent releases (this count includes any already shown releases) + +## Tenants view + +This view is shown if: + +- Your project settings **allow** tenanted deployments + +You’ll see **all** of your tenants in your project and a selection of releases deployed to them. + +From this view you can filter by release and then deploy the selected release into each tenant’s environments. + +:::figure +![Project dashboard tenants view](/docs/projects/dashboard/project-dashboard-tenants.jpeg) +::: + +### Which releases are shown in the tenants view? + +- For each **tenant and environment combination**: + - The most recently deployed release is shown. +- If untenanted deployments are allowed: + - For each **environment**: + - The most recently deployed, untenanted release is shown. + +### Alternative tenants views + +- Grouping: + - When **no grouping** is selected: + - The environments shown are from your **project’s lifecycle**. + - When **grouping by channel** is selected: + - Each channel’s environments are from that **channel’s lifecycle**. +- Project settings for tenanted and untenanted deployments: + - **Both tenanted and untenanted** deployments are allowed: + - All untenanted deployments are summarized in the first row, labeled ‘Untenanted’. + - **Only tenanted** deployments are allowed: + - No untenanted deployments are shown on the dashboard. diff --git a/src/pages/docs/projects/project-triggers/deployment-target-triggers.md b/src/pages/docs/projects/project-triggers/deployment-target-triggers.md index 7921b54816..a47a1b4316 100644 --- a/src/pages/docs/projects/project-triggers/deployment-target-triggers.md +++ b/src/pages/docs/projects/project-triggers/deployment-target-triggers.md @@ -26,13 +26,13 @@ Deployment target triggers can be triggered by any machine-related event. A sche Events have been placed into the following pre-defined groups: -| Event group | Included Events | -| ----------- | --------------- | -| **Machine events** | Machine cleanup failed, Machine created, Machine deployment-related property modified, Machine disabled, Machine enabled, Machine found healthy, Machine found to be unavailable, Machine found to be unhealthy, Machine found to have warnings | -| **Machine critical-events** | Machine cleanup failed, Machine found to be unavailable | -| **Machine becomes available for deployment** | Machine enabled, Machine found healthy, Machine found to have warnings | -| **Machine is no longer available for deployment** | Machine disabled, Machine found to be unavailable, Machine found to be unhealthy | -| **Machine health changed** | Machine found healthy, Machine found to be unavailable, Machine found to be unhealthy, Machine found to have warnings | +| Event group | Included Events | +| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Machine events** | Machine cleanup failed, Machine created, Machine deployment-related property modified, Machine disabled, Machine enabled, Machine found healthy, Machine found to be unavailable, Machine found to be unhealthy, Machine found to have warnings | +| **Machine critical-events** | Machine cleanup failed, Machine found to be unavailable | +| **Machine becomes available for deployment** | Machine enabled, Machine found healthy, Machine found to have warnings | +| **Machine is no longer available for deployment** | Machine disabled, Machine found to be unavailable, Machine found to be unhealthy | +| **Machine health changed** | Machine found healthy, Machine found to be unavailable, Machine found to be unhealthy, Machine found to have warnings | :::div{.success} For the majority of cases where you want to auto-deploy your project as new deployment targets become available, we advise you use only the **Machine becomes available for deployment** event group. @@ -74,8 +74,8 @@ Deployment target triggers let you configure unattended deployment behavior that When a deployment target trigger fires, the following rules are applied: -- By default, Octopus will re-run the *currently successful* deployment for the project/environment/tenant combination. You can override this behavior by configuring an [auto deploy override](/docs/octopus-rest-api/octopus-cli/create-autodeployoverride). Note, if multiple identical deployment targets all become available within the same 30 second polling window, they will all be included in the same automatic deployment. This could happen if you scale your web farm up by four nodes, and all four nodes finish provisioning within the same time window. However, this kind of behavior should not be expected or relied on (one or more of the targets might fall outside the 30 second window). -- The steps that were run for the *currently successful* deployment will be run for the deployment targets that triggered the deployment. This includes [manual intervention](/docs/projects/built-in-step-templates/manual-intervention-and-approvals/) and [guided failure](/docs/releases/guided-failures) steps. Note, if you skip steps in a manual deployment, they will be skipped in the subsequent automatic deployment. If you need to run a deployment and skip some steps, there are two ways you can reset the skipped steps: +- By default, Octopus will re-run the _currently successful_ deployment for the project/environment/tenant combination. You can override this behavior by configuring an [auto deploy override](/docs/octopus-rest-api/octopus-cli/create-autodeployoverride). Note, if multiple identical deployment targets all become available within the same 30 second polling window, they will all be included in the same automatic deployment. This could happen if you scale your web farm up by four nodes, and all four nodes finish provisioning within the same time window. However, this kind of behavior should not be expected or relied on (one or more of the targets might fall outside the 30 second window). +- The steps that were run for the _currently successful_ deployment will be run for the deployment targets that triggered the deployment. This includes [manual intervention](/docs/projects/built-in-step-templates/manual-intervention-and-approvals/) and [guided failure](/docs/releases/guided-failures) steps. Note, if you skip steps in a manual deployment, they will be skipped in the subsequent automatic deployment. If you need to run a deployment and skip some steps, there are two ways you can reset the skipped steps: 1. Re-running the entire deployment of the same release again (we generally recommend designing your steps so they can be re-run without negative side-effects). 2. Configuring an [auto deploy override](/docs/octopus-rest-api/octopus-cli/create-autodeployoverride) for the same release to the same environment/tenant (this will result in a new deployment being generated without the manually skipped steps). - If a deployment of a release fails, Octopus will continue deploying the last successful deployment. This ensures auto-deployments will continue, even if a release has been updated and failed. @@ -102,7 +102,7 @@ The [Chain Deployment](https://library.octopus.com/step-template/actiontemplate- ### Specifying a specific release to be deployed -If you need to specify a specific release, either because the release hasn't been deployed yet, or Octopus is calculating the wrong release for a particular situation, you can configure an [auto deploy override](/docs/octopus-rest-api/octopus-cli/create-autodeployoverride/) to override the default automatic deployment behavior. This is useful for scenarios like [immutable infrastructure](/docs/deployments/patterns/elastic-and-transient-environments/immutable-infrastructure/), [deploying to transient targets](/docs/deployments/patterns/elastic-and-transient-environments/deploying-to-transient-targets), and force deployment target triggers to use a specific release for a specific environment/tenant. +If you need to specify a specific release, either because the release hasn't been deployed yet, or Octopus is calculating the wrong release for a particular situation, you can configure an [auto deploy override](/docs/octopus-rest-api/octopus-cli/create-autodeployoverride/) to override the default automatic deployment behavior. This is useful for scenarios like [immutable infrastructure](/docs/deployments/patterns/elastic-and-transient-environments/immutable-infrastructure/), [deploying to transient targets](/docs/deployments/patterns/elastic-and-transient-environments/deploying-to-transient-targets), and force deployment target triggers to use a specific release for a specific environment/tenant. ## Deployment target trigger subscription notifications @@ -114,7 +114,7 @@ There are a number of reasons why automatic deployments may not work the way you ### Is the dashboard green? -Octopus will attempt to automatically deploy the current releases for the environments that are appropriate for a machine. The current release is the one that was most recently *successfully* deployed as shown on the project dashboard. +Octopus will attempt to automatically deploy the current releases for the environments that are appropriate for a machine. The current release is the one that was most recently _successfully_ deployed as shown on the [project dashboard](/docs/projects/project-dashboard). - Octopus will not automatically deploy a release if the deployment for that release was not successful (this can be a failed deployment or even a canceled deployment)