terraform-provider-stackitprivatepreview/docs/index.md

STACKIT Provider

The STACKIT provider is the official Terraform provider to integrate all the resources developed by STACKIT.

Example Usage

provider "stackit" {
  region = "eu01"
}

# Authentication

# Token flow
provider "stackit" {
  region                = "eu01"
  service_account_token = var.service_account_token
}

# Key flow
provider "stackit" {
  region              = "eu01"
  service_account_key = var.service_account_key
  private_key         = var.private_key
}

# Key flow (using path)
provider "stackit" {
  region                   = "eu01"
  service_account_key_path = var.service_account_key_path
  private_key_path         = var.private_key_path
}

Authentication

To authenticate, you will need a service account. Create it in the STACKIT Portal an assign it the necessary permissions, e.g. project.owner. There are multiple ways to authenticate:

• Key flow (recommended)
• Token flow

When setting up authentication, the provider will always try to use the key flow first and search for credentials in several locations, following a specific order:

1. Explicit configuration, e.g. by seting the field stackit_service_account_key_path in the provider block (see example below)

2. Environment variable, e.g. by setting STACKIT_SERVICE_ACCOUNT_KEY_PATH

3. Credentials file

   The SDK will check the credentials file located in the path defined by the STACKIT_CREDENTIALS_PATH env var, if specified, or in $HOME/.stackit/credentials.json as a fallback. The credentials should be set using the same name as the environment variables. Example:

   {
     "STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token",
     "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json",
     "STACKIT_PRIVATE_KEY_PATH": "path/to/private_key.pem"
   }
   

Key flow

To use the key flow, you need to have a service account key and an RSA key-pair. To configure it, follow this steps:

The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. project.owner.

1. In the Portal, go to the Service Accounts tab, choose a Service Account and go to Service Account Keys to create a key.

• You can create your own RSA key-pair or have the Portal generate one for you.

2. Save the content of the service account key and the corresponding private key by copying them or saving them in a file.

   Hint: If you have generated the RSA key-pair using the Portal, you can save the private key in a PEM encoded file by downloading the service account key as a PEM file and using openssl storeutl -keys <path/to/sa_key_pem_file> > private.key to extract the private key from the service account key.

The expected format of the service account key is a json with the following structure:

{
  "id": "uuid",
  "publicKey": "public key",
  "createdAt": "2023-08-24T14:15:22Z",
  "validUntil": "2023-08-24T14:15:22Z",
  "keyType": "USER_MANAGED",
  "keyOrigin": "USER_PROVIDED",
  "keyAlgorithm": "RSA_2048",
  "active": true,
  "credentials": {
    "kid": "string",
    "iss": "my-sa@sa.stackit.cloud",
    "sub": "uuid",
    "aud": "string",
    (optional) "privateKey": "private key when generated by the SA service"
  }
}

3. Configure the service account key and private key for authentication in the SDK by following one of the alternatives below:
   • setting the fiels in the provider block: service_account_key or service_account_key_path, private_key or private_key_path
   • setting environment variables: STACKIT_SERVICE_ACCOUNT_KEY_PATH and STACKIT_PRIVATE_KEY_PATH
   • setting STACKIT_SERVICE_ACCOUNT_KEY_PATH and STACKIT_PRIVATE_KEY_PATH in the credentials file (see above)

Token flow

Using this flow is less secure since the token is long-lived. You can provide the token in several ways:

1. Setting the field service_account_token in the provider
2. Setting the environment variable STACKIT_SERVICE_ACCOUNT_TOKEN
3. Setting it in the credentials file (see above)

Schema

Optional

• argus_custom_endpoint (String) Custom endpoint for the Argus service
• credentials_path (String) Path of JSON from where the credentials are read. Takes precedence over the env var STACKIT_CREDENTIALS_PATH. Default value is ~/.stackit/credentials.json.
• dns_custom_endpoint (String) Custom endpoint for the DNS service
• jwks_custom_endpoint (String) Custom endpoint for the jwks API, which is used to get the json web key sets (jwks) to validate tokens when using the key flow
• loadbalancer_custom_endpoint (String) Custom endpoint for the Load Balancer service
• logme_custom_endpoint (String) Custom endpoint for the LogMe service
• mariadb_custom_endpoint (String) Custom endpoint for the MariaDB service
• mongodbflex_custom_endpoint (String) Custom endpoint for the MongoDB Flex service
• objectstorage_custom_endpoint (String) Custom endpoint for the Object Storage service
• opensearch_custom_endpoint (String) Custom endpoint for the OpenSearch service
• postgresflex_custom_endpoint (String) Custom endpoint for the PostgresFlex service
• postgresql_custom_endpoint (String) Custom endpoint for the PostgreSQL service
• private_key (String) Private RSA key used for authentication. If set alongside the service account key, the key flow will be used to authenticate all operations.
• private_key_path (String) Path for the private RSA key used for authentication. If set alongside the service account key, the key flow will be used to authenticate all operations.
• rabbitmq_custom_endpoint (String) Custom endpoint for the RabbitMQ service
• redis_custom_endpoint (String)
• region (String) Region will be used as the default location for regional services. Not all services require a region, some are global
• resourcemanager_custom_endpoint (String) Custom endpoint for the Resource Manager service
• secretsmanager_custom_endpoint (String) Custom endpoint for the Secrets Manager service
• service_account_email (String) Service account email. It can also be set using the environment variable STACKIT_SERVICE_ACCOUNT_EMAIL. It is required if you want to use the resource manager project resource.
• service_account_key (String) Service account key used for authentication. If set alongside private key, the key flow will be used to authenticate all operations.
• service_account_key_path (String) Path for the service account key used for authentication. If set alongside the private key, the key flow will be used to authenticate all operations.
• service_account_token (String) Token used for authentication. If set, the token flow will be used to authenticate all operations.
• ske_custom_endpoint (String) Custom endpoint for the Kubernetes Engine (SKE) service
• token_custom_endpoint (String) Custom endpoint for the token API, which is used to request access tokens when using the key flow