terraform-provider-stackitprivatepreview/docs/index.md

STACKIT Terraform Provider

The STACKIT Terraform 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 and 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 setting 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 provider 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 provider 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)

Backend configuration

To keep track of your terraform state, you can configure an S3 backend using STACKIT Object Storage.

To do so, you need an Object Storage S3 bucket and credentials to access it. If you need to create them, check Getting Started - Object Storage.

Once you have everything setup, you can configure the backend by adding the following block to your terraform configuration:

terraform {
  backend "s3" {
    bucket = "BUCKET_NAME"
    key    = "path/to/key"
    endpoints = {
      s3 = "https://object.storage.eu01.onstackit.cloud"
    }
    region                      = "eu01"
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_s3_checksum            = true
    skip_requesting_account_id  = true
    secret_key                  = "SECRET_KEY"
    access_key                  = "ACCESS_KEY"
  }
}

Note: AWS specific checks must be skipped as they do not work on STACKIT. For details on what those validations do, see here.

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
• iaas_custom_endpoint (String) Custom endpoint for the IaaS service
• jwks_custom_endpoint (String, Deprecated) 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, relevant for the key flow. It takes precedence over the private key that is included in the service account key.
• private_key_path (String) Path for the private RSA key used for authentication, relevant for the key flow. It takes precedence over the private key that is included in the service account key.
• rabbitmq_custom_endpoint (String) Custom endpoint for the RabbitMQ service
• redis_custom_endpoint (String) Custom endpoint for the Redis service
• 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, 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, 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