Documentation and SupportDocumentation and Support

Tenant tags

In Octopus, tenant tags help you to classify your tenants using custom tags that meet your needs, and tailor tenanted deployments for your projects and environments. Tenant tags also make it easier to work with tenants as groups instead of individuals. Using tags you can apply meaningful metadata to tenants, to describe them using your own terminology, improve search and filtering, and tailor the deployment process to their needs.

What can you do with tenant tags?

Octopus allows you to group similar tags together into tag sets. This enables you to more easily understand which tags fit together, what effect they should have on tenanted deployments, and design powerful tag-based queries using combinations of tags:

With tenant tags you can:

  • Classify your tenants using custom tags that match your situation.
  • Find tenants more quickly by searching and filtering with tags.
  • Group the project overview by tag set.
  • Deploy to multiple tenants at the same time - read more below.
  • Customize the deployment process for tenants.
  • Scope project variables to tags.
  • Design a multi-tenant hosting model - read more in our tenant infrastructure section.
  • Design a multi-tenant deployment process for SaaS applications, regions and more - for further details, see our guides.
  • Control which releases can be deployed to tenants using channels - read more in our tenant lifecycle section.

Managing Tenant Tags

Go to Library ➜ Tenant tag sets to create, modify and reorder tag sets and tags.

Design your tag sets carefully

We suggest taking some time to design your tag sets based on how you will apply them to your projects and environments. Our recommendation is to make sure each of your tag sets are orthogonal, like different axes on a chart. This kind of design is important because of how tags are combined in tag filters.

Let’s look at an Example tag set design :

  • Importance (VIP, Standard, Trial): concerned with classifying tenants so they can be found easily.
  • Hosting Region (West US, East US 2): concerned with how the tenant software is hosted - read more about this in our tenant infrastructure section.
  • Release ring (Alpha, Beta, Stable): concerned with when the tenant’s applications are upgraded in relationship to other tenants - read more about this in our guide.

This kind of tag set design will make it easier for each different class of Octopus user to understand which tags apply to their area, and the impact it will have on your tenanted deployments.

Ordering tag sets and tags

Order is important for tag sets, and tags within those tag sets. Octopus will sort tag sets and tags based on the order you define in the library. This allows you to tailor the Octopus user interface to your own situation.

This example of configuring a tenanted deployment target shows how the tenant filter field order is defined based on the order of the tag sets and tags in the library.

Tag-based filters

Once you have defined some tag sets and tags you can start leveraging those tags to tailor your environments and deployments.

Combinational logic When filtering tenants, Octopus will combine tags within the same tag set using the OR operator, and combine tag sets using the AND operator.

Let’s take a look at an example:

In this example Octopus will execute a query like the one shown below:

TenantsNamed("Capital Animal Hospital") UNION TenantsTagged(VIP AND (Alpha OR Beta))

When paired with a well-structured tag design, this logic will enable you to tailor your tenanted deployments in interesting and effective ways.

Tips for working with tenant filters

  • Only specify a tenant “by name” (explicitly) if you absolutely want that tenant included in the result, otherwise leave it blank
  • A filter with tags in the same tag set will be more inclusive since they are combined using OR
  • A filter with tags across different tag sets will become more reductive since they are combined using AND

Referencing tenant tags

If you want to use tenant tags to automate Octopus Deploy you should use the Canonical Name for the Tag which looks like this: Tag Set Name/Tag Name

Consider an example deploying a release to the tenants tagged with the Alpha tag in the Release Ring tag set.

# Deploys My Project 1.0.1 to all tenants tagged as in the Alpha ring
./octo deploy-release --server= --apiKey=API-1234567890123456 --project="My Project" --version="1.0.1" --tenantTag="Release ring/Alpha"

Some places you can use tags are:

Deploying to multiple tenants using tags

You can create tenant tag sets specifically to help with deployments and rolling out upgrades. Quite often, you want to deploy targeted releases to your testers, and once testing is finished, you want to flight/prove that upgrade with a smaller group of tenants before rolling it out to the rest of your tenants. This is also useful when breaking down large amounts of tenants into smaller deployments. Here we outline the steps needed to design that kind of process using tenant tags.

Step 1: Create a tag set called Upgrade ring

Firstly we create a tag set called Upgrade ring with tags allowing each tenant to choose how early in the development/test cycle they want to receive upgrades.

  1. Create a new tenant tag set called Upgrade ring and add tags for Tester, Early adopter, and Stable.
  2. Make sure to choose colors that highlight different tenants.

Step 2: Configure a test tenant

Either create a new tenant, or configure an existing tenant. This tenant will receive upgrades before any of the other configured tenants.

  1. Tag your test tenant(s) with Tester.

Step 3: Configure some early adopter tenants and stable tenants

Optionally, configure some external tenants as opting into early or stable releases to see the effect.

  1. Find or create some tenants and tag them as either Stable or Early adopter.

Step 4: Deploy

Now it’s time to deploy using tenant tags as a way to select multiple tenants easily. In this example, we will deploy version 1.0.1 to all of the tenants tagged with Tester who are connected to the Test environment. You can use multiple tags and complex tag queries to achieve other interesting scenarios.

You can also use the Project Overview to deploy to groups of tenants by grouping the dashboard, selecting a release, and clicking the Deploy to all button.

Learn more

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023