Restructuring Accounts and Clusters via Instaclustr Organizations
This document is targeting existing customers who would like to restructure their accounts into an Instaclustr Organization and move clusters from one account to another.
For new customers, we recommend using the Instaclustr Organization when you sign up with us. This is because it helps structuring your resources in an organized manner as you start creating more accounts.
To learn more about Instaclustr Organizations, read our blog post and our Organization Management documentation on the Instaclustr website.
Table of Contents
Scenario
You have multiple accounts within the Instaclustr Console and each account has running clusters under it. Each account has its own contact details which Instaclustr uses to send information to in different circumstances (e.g. notifying you of a cluster issue). By having your accounts into organizations, you can easily manage organization owners, organization details or billing information for all of them at once.
It is possible that over time, there will be changes to an account’s contact details, which will make it no longer fit for some of its clusters. If this is the case, you can migrate your clusters to a better fit account, or even a completely new account, just by using Instaclustr Organization’s Migrate Clusters feature.
Instaclustr Organization Feature
Instaclustr Organizations are a way for you to manage all your Instaclustr accounts in a single, easily accessible location. Simply put, an Instaclustr Organization is an additional layer in our permissions model that allows our users to group their accounts. Benefits of Instaclustr Organizations include:
- Centralized billing management for multiple accounts
- Centralized single sign-on (SSO) configuration for multiple accounts
- Control over account creation
- Migrating clusters between managed accounts
- Centrally managed contact details
Impacts of Restructuring Accounts and Clusters
As a result of moving clusters to new or other existing accounts, several integrations could be impacted:
- Single Sign-On (SSO) via your identity provider.
- Integration using Instaclustr API key (e.g. Prometheus, Terraform).
Single Sign-On (SSO) Integration
Note: Impact can be mitigated prior to cluster migration.
If you are creating new accounts, and your Instaclustr Organization has SSO enabled, it is better to make sure your user can access the new accounts before moving cluster into them. This is done from your identity provider (IdP), where you can see how existing accounts are set up. Essentially, you synchronise your groups and assign your users to the new groups representing your new Instaclustr accounts.
For more information about how SSO is integrated within an Instaclustr Organization, please read our documentation. Also, if you would like to enable SSO for one of your accounts, please contact [email protected].
Integration using Instaclustr API Key
A Cluster Management API key is a key specific to an account which can access the clusters within that account. By moving a cluster to a different account, the existing API key can no longer be authorised to manage that specific cluster. In such cases, a newly generated API key from the target account is required.
The sections below describe two popular integrations with the Instaclustr API keys.
Prometheus
Note: Impact can be mitigated prior to cluster migration.
You can generate a new Prometheus API key from the target account and set up scraper against it, prior to cluster migration. This makes sure your metrics scraper is ready to pull metrics data right after your clusters are migrated.
Terraform
Note: Impact can be mitigated after cluster migration.
You can generate a new Provisioning API key from target account and update terraform configuration through Terraform Provider alias. A Terraform Provider alias allows users to define multiple providers from the same source but with different settings.
Terraform Provider Alias
As previously mentioned, an alias is a Terraform Provider feature which allows you to define multiple configurations for the same provider (source: HashiCorp Developer documentation).
A default provider is a provider block that contains a configuration. In the example below, we have a provider block called aws which contains a configuration argument called region.
1 2 3 |
provider "aws" { region = "us-east-1" } |
By adding an alias to it, we would be able to use the same provider with a different configuration for the same argument.
1 2 3 4 |
provider "aws" { alias = "west" region = "us-west-2" } |
As a result, when retrieving the default region via provider.aws.region, the value will us-east-1, but when using aliases (provider.aws.west.region) it will be us-west-2 instead.
1 2 3 4 5 6 7 8 9 10 11 |
resource “aws_s3_bucket” "my_default_bucket" { provider = aws bucket = “my-bucket” region = provider.aws.region } resource “aws_s3_bucket” "my_alias_bucket" { provider = aws.west bucket = “my-other-bucket” region = provider.aws.west.region } |
This is useful in instances when a user wants to dynamically use certain arguments from either the default or aliased provider within their Terraform configurations.
Terraform Provider Alias and Instaclustr Accounts
In the Instaclustr’s integration case, multiple Instaclustr Terraform Providers will use different Instaclustr Provisioning API keys. As a result, a provider alias represents an account ID, which can be assigned individually to the Terraform resource.
The snippets below present a simple example of such alias usage. It starts off by configuring the Terraform version and the default provider called instaclustr, which is using the existing account’s API key.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
terraform { required_providers { instaclustr = { source = "instaclustr/instaclustr" version = ">= 2.0.0, < 3.0.0" } } } # original provider represents existing account's ID provider "instaclustr" { terraform_key = "Instaclustr-Terraform ${var.existing_account_user_key}" } |
It then adds the aliased instaclustr provider which will make use of the new account’s API key.
1 2 3 4 5 |
# provider alias represents new account's ID provider "instaclustr" { alias = "new_account" terraform_key = "Instaclustr-Terraform ${var.new_account_user_key}" } |
It then assigns the alias to the migrated resources. The existing account’s resources will use the default provider’s terraform_key, not the aliased one.
1 2 3 4 5 6 7 8 9 10 |
# cluster stays in same account -> no change resource "instaclustr_cassandra_cluster_v2" "existing_cassandra_cluster" { ... } # cluster moves to new account -> update with provider alias resource "instaclustr_kafka_cluster_v2" "migrated_kafka_cluster" { provider = instaclustr.new_account ... } |
After assigning an alias to the migrated resources, you should be able to successfully run:
1 |
terraform apply |