Merge pull request #2515 from OctopusDeploy/bobjwalker/dr-guide-best-practice

Wrapping up HA/DR Guides

Author: BobJWalker

src/pages/docs/best-practices/deployments/environments-and-deployment-targets-and-roles.md

@@ -0,0 +1,114 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2023-01-01
+modDate: 2024-06-27
+title: Environments, Deployment Targets, and Target Tags
+description: Guidelines and recommendations for configuring environments, deployment targets, and lifecycles in Octopus Deploy.
+navOrder: 30
+hideInThisSection: true
+---
+
+[Deployment targets](/docs/infrastructure/deployment-targets/) are what Octopus Deploy deploys to.  They can be Windows servers, Linux servers, Kubernetes (K8s) clusters, Azure Web Apps, and more.  Please refer to the [Deployment targets](/docs/infrastructure/deployment-targets/) for an up to date list on deployment targets.  [Environments](/docs/infrastructure/environments) are how you organize your deployment targets into groups that represent different stages of your deployment pipeline.  These stages are typically given names such as **development**, **test**, and **production**.  [Target tags](/docs/infrastructure/deployment-targets/target-tags) (formerly target roles) are a filter to select specific deployment targets in an environment.
+
+## Deployment Target, Environment, and Target Tag relationship \{#deployment-target-environment-and-role-relationship}
+Environments are how you group deployment targets in a stage in your deployment pipeline.  Target tags are how you identify which deployment targets you wish to deploy to in that specific stage.
+
+When you register a deployment target, you must provide at least one environment and one target tag.
+
+:::figure
+![Environments and target tags for a deployment target](/docs/getting-started/best-practices/images/registering-deployment-target.png)
+:::
+
+In the deployment process, you assign steps to run on deployment targets with specific target tags.
+
+:::figure
+![Deployment process target tag assignment](/docs/getting-started/best-practices/images/target-roles-in-deployment-process.png)
+:::
+
+For example, imagine you have three deployment targets in the **development** environment with the following target tags:
+- dev-server-01: `hello-world`, `hello-world-api`, `hello-world-ui`, and `IIS-Server-2019` tags
+- dev-server-02: `hello-world-api` and `IIS-Server-2019` tags
+- dev-server-03: `octo-petshop-api` and `IIS-Server-2019` tags
+
+The deployment process from above targets the `hello-world-api` tag.  When a deployment to the **development** environment is triggered, Octopus will only select the two servers assigned to the **development** environment AND with the `hello-world-api` target tag.
+
+:::figure
+![Octopus selecting deployment targets](/docs/getting-started/best-practices/images/selecting-target-roles.png)
+:::
+
+:::div{.hint}
+Assigning multiple target tags to a deployment step results in an OR statement.  For example, adding the target tag `octo-petshop-api` to the deployment process and deploying to the **development** environment will result in the filtering logic to be: 
+
+All servers in the **development** environment AND the servers with the target tags `hello-world-api` OR `octo-petshop-api`.  
+
+For software developers, you can rewrite that sentence as:
+
+`If (server.Environment == "development" && (server.TargetTag == "hello-world-api" || server.TargetTag == "octo-petshop-api"))`
+
+Using the example from above, Octopus would select all three servers.
+:::
+
+## Environment and Target Tag usage differences \{#environment-and-role-usage-differences}
+
+Environments are designed as a macro grouping of deployment targets meant for use across multiple projects, variable sets, and more.  Below is a list of items where environments are used:
+
+- Lifecycles
+- Project Variable scoping
+- Variable Set scoping
+- Log filtering
+- Tenant variable scoping
+- Accounts
+- Certificates
+- Deployment targets
+- Process step scoping (only run a step on a specific environment)
+
+Target tags are designed as a micro grouping of deployment targets meant to deploy a specific project or application component.  Below is a list of items where tags are used:
+
+- Project Variable scoping
+- Process step scoping (run this step for specific environments)
+
+:::div{.hint}
+A deployment target can be assigned to 1 to N environments and 1 to N target tags.  
+:::
+
+## Environments
+
+Adding an environment is a non-trivial task, as it involves adding/updating additional deployment targets, variable scoping, lifecycles accounts, certificates, and more.  There is a direct correlation between a high number of environments and poor maintainability, usability, and performance.  
+
+Our recommendations for environments are:
+- Keep the number of environments per space to be between 2 and 10.  
+- Name environments to match your company's terminology so you can re-use them across projects.  Common names include **development**, **test**, **QA**, **acceptance**, **uat**, and **production**.
+- If you have between one and five data centers (including cloud regions), it's okay to have an environment per data center.  For example, **Production - AU** for a data center in Australia and **Production - Central US** for the Azure Central US region. If you have more than five data centers, consider [tenants](/docs/tenants) where each data center is a tenant.
+- It's okay to have team-specific environments, similar to data center environments.  Although if you have more than five or six teams, consider [tenants](//docs/tenants/) where each team is a tenant.
+
+Anti-patterns to avoid are:
+- Project names in your environments.  An environment name of **QA - OctoPetShop** indicates you need to either have more specific target tags on your deployment targets or you need to leverage spaces to isolate that application.  Project-specific environments are a good indicator to consider [spaces](/docs/administration/spaces).  
+- Branch names in your environment names.  Consider using temporary [tenants](/docs/tenants) for your branch names or storing your branch name in a pre-release tag in the release version.
+- A single deployment environment, **production**.  You should have at least one test environment to test and verify your release.
+
+## Target Tags \{#roles}
+
+There is also a direct correlation between generic target tags, such as `web-server` and the number of environments.  As stated earlier, adding an environment is a non-trivial task, and leads to maintenance and performance overhead.  The goal is to keep the number of environments low.
+
+Using the generic target tag `web-server` will pick all the servers in a specific environment.  For example, you have 25 servers in **production** with the tag `web-server`.  When you deploy to **production**, Octopus will pick all 25 servers, but you only want to deploy to 4 of them.  There is no automatic way to limit the servers picked without either creating a specific tag `hello-world-api` or creating a new environment.
+
+Generic target tags also impact your future flexibility.  For example, using `web-server` for 100 projects would require all targets on all environments to host those same 100 projects.  If you were to decide in six months to split up those servers, you'd have to update over 100 projects.
+
+Our recommendations for target tags are:
+- Avoid generic tags, such as `web-server`, whenever possible.
+- Use specific tags, `hello-world-api`, to uniquely identify a project and component to deploy.  Use those specific tags in your deployment process.
+- Use architecture and platform-specific tags, for example, `IIS-Server-Windows-2019`.  Use those tags for everyday maintenance tasks; updating to the latest version of Node.js, or installing a patch.
+
+:::div{.hint}
+Add an environment for a business need; a new data center is brought online, you are adding your disaster recovery location into Octopus, or adding the ability for customers to test changes prior to **production**.  
+
+Add a new target tag to group servers and filter servers within each environment.
+:::
+
+## Further reading
+
+For further reading on environments, deployment targets, and target tags in Octopus Deploy please see:
+
+- [Deployment Targets](/docs/infrastructure/deployment-targets)
+- [Environments](/docs/infrastructure/environments)
+- [Target Tags](/docs/infrastructure/deployment-targets/target-tags#create-target-roles)

src/pages/docs/best-practices/deployments/index.md

@@ -14,7 +14,9 @@ This section covers our recommendations and implementation guides for configurin
 
 The topics covered are:
 
+- [Environments, deployment targets, and target tags](/docs/best-practices/deployments/environments-and-deployment-targets-and-roles)
 - [Lifecycles and Environments](/docs/best-practices/deployments/lifecycles-and-environments)
+- [Projects and Project group structure](/docs/best-practices/deployments/projects-and-project-groups)
 - [Deployment and Runbook Process](/docs/best-practices/deployments/deployment-and-runbook-processes)
 - [Variables](/docs/best-practices/deployments/variables)
 - [Step Templates and Script Modules](/docs/best-practices/deployments/step-templates-and-script-modules)

src/pages/docs/best-practices/deployments/projects-and-project-groups.md

@@ -0,0 +1,58 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2023-01-01
+modDate: 2023-10-04
+title: Projects and Project Groups Structure
+description: Guidelines and recommendations for configuring projects and project groups in Octopus Deploy.
+navOrder: 50
+hideInThisSection: true
+---
+
+[Projects](/docs/projects) store the deployment configuration for an application.  For each project, you can define a deployment process and runbooks to manage your infrastructure, variables, the environments where the software is deployed, and your software releases.  Project groups allow you to group like projects together.  
+
+## Project structure
+
+We recommend thinking of projects and project groups this way:
+
+- Project Group = Software Suite
+- Project = Application
+
+An application represents all the tightly coupled components required for the software to run.  Some examples of applications are:
+
+- A microservice running in a container monitoring a queue for work.
+- An N-Tier Web Application with a WebUI, WebAPI, back-end Service, and Database.
+- A back-end service that processes files from a file share based on a schedule.
+- A monolithic application with dozens of components.
+
+All the components in a single "solution" or built in the same configuration should be deployed together.  The deployment process should always deploy all the components.  Trying to skip a component because it "didn't change" can reduce deployment time but increases the risk of bugs or failures because something was missed.  
+
+If you want to have a project per component, you need to ensure each component is decoupled from one another and can be deployed on a separate schedule.  
+
+:::div{.hint}
+Previous versions of this guide recommended having a project per component.  Octopus Deploy now includes new features, including ITSM integration, Config as Code, and more options for variable run conditions.  There is also a logistical overhead with a project per component.  That recommendation was made in 2021.  At that time, a project per component made sense.  It is no longer applicable with the 2023 version of Octopus Deploy.
+:::
+
+## Anti-patterns to avoid
+
+A project should deploy all the coupled components of an application (WebUI, WebAPI, Service, Database).  Some common anti-patterns we've seen you should avoid are:
+
+- A project per component in an application.  If the components are referenced in the same "solution" or built in the same build configuration, they need to be deployed together.
+- A project per application, per environment, such as `OctoPetShop_Dev`, `OctoPetShop_Test`, and so on.  That is impossible to maintain and track versions.
+- A project per customer or physical location, such as `OctoPetShop_AustinEast`, `OctoPetShop_AustinWest`, and so on.  This is impossible to maintain, you'd need a syncing process for all projects.  Use [multi-tenancy](/docs/tenants) instead.
+
+## Cumulative changes
+
+Octopus Deploy expects any application component it deploys to contain everything that the component needs.  If you are deploying a web application, the deployment should include all the JavaScript, CSS, binaries, HTML files, etc., needed to run that web application.  It shouldn't just be a delta change of a few HTML files or binaries.  Octopus Deploy expects that for a variety of reasons.
+
+- All releases will need to be deployed to all environments.  
+- Deploying only delta changes requires you to always deploy all versions in a specific order.  
+- If a new deployment target (web server) is created, you will have to deploy all versions to that new target rather than the latest.
+- You'll need a mechanism to create roll-up releases; otherwise, the list of versions to deploy when a new target is added will grow and become unwieldy.
+- It'll be near impossible to roll back to a previous version of the code.
+
+## Further reading
+
+For further reading on projects and project groups in Octopus Deploy, please see:
+
+- [Projects](/docs/projects)
+- [Multi-Tenancy](/docs/tenants)