189 lines
11 KiB
Markdown
189 lines
11 KiB
Markdown
# STACKIT Terraform Provider
|
|
|
|
The STACKIT Terraform provider is the official Terraform provider to integrate all the resources developed by [STACKIT](https://www.stackit.de/en/).
|
|
|
|
## Example Usage
|
|
|
|
```terraform
|
|
provider "stackit" {
|
|
default_region = "eu01"
|
|
}
|
|
|
|
# Authentication
|
|
|
|
# Token flow
|
|
provider "stackit" {
|
|
default_region = "eu01"
|
|
service_account_token = var.service_account_token
|
|
}
|
|
|
|
# Key flow
|
|
provider "stackit" {
|
|
default_region = "eu01"
|
|
service_account_key = var.service_account_key
|
|
private_key = var.private_key
|
|
}
|
|
|
|
# Key flow (using path)
|
|
provider "stackit" {
|
|
default_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](https://docs.stackit.cloud/stackit/en/service-accounts-134415819.html). Create it in the [STACKIT Portal](https://portal.stackit.cloud/) 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 `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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
The following instructions assume that you have created a service account and assigned the necessary permissions to it, e.g. `project.owner`.
|
|
|
|
To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it.
|
|
|
|
When creating the service account key, a new pair can be created automatically, which will be included in the service account key. This will make it much easier to configure the key flow authentication in the [STACKIT Terraform Provider](https://github.com/stackitcloud/terraform-provider-stackit), by just providing the service account key.
|
|
|
|
**Optionally**, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the [STACKIT Terraform Provider](https://github.com/stackitcloud/terraform-provider-stackit), additionally to the service account key. Check the STACKIT Knowledge Base for an [example of how to create your own key-pair](https://docs.stackit.cloud/stackit/en/usage-of-the-service-account-keys-in-stackit-175112464.html#UsageoftheserviceaccountkeysinSTACKIT-CreatinganRSAkey-pair).
|
|
|
|
To configure the key flow, follow this steps:
|
|
|
|
1. Create a service account key:
|
|
|
|
- Use the [STACKIT Portal](https://portal.stackit.cloud/): go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html)
|
|
|
|
2. Save the content of the service account key by copying it and saving it in a JSON file.
|
|
|
|
The expected format of the service account key is a **JSON** with the following structure:
|
|
|
|
```json
|
|
{
|
|
"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 for authentication in the provider by following one of the alternatives below:
|
|
|
|
- setting the fields in the provider block: `service_account_key` or `service_account_key_path`
|
|
- setting the environment variable: `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
|
|
- setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` in the credentials file (see above)
|
|
|
|
> **Optionally, only if you have provided your own RSA key-pair when creating the service account key**, you also need to configure your private key (takes precedence over the one included in the service account key, if present). **The private key must be PEM encoded** and can be provided using one of the options below:
|
|
>
|
|
> - setting the field in the provider block: `private_key` or `private_key_path`
|
|
> - setting the environment variable: `STACKIT_PRIVATE_KEY_PATH`
|
|
> - setting `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](https://developer.hashicorp.com/terraform/language/settings/backends/s3) using [STACKIT Object Storage](https://docs.stackit.cloud/stackit/en/object-storage-s3-compatible-71009778.html).
|
|
|
|
To do so, you need an Object Storage [S3 bucket](https://docs.stackit.cloud/stackit/en/basic-concept-objectstorage-71009785.html#BasicConceptObjectStorage-Buckets) and [credentials](https://docs.stackit.cloud/stackit/en/basic-concept-objectstorage-71009785.html#BasicConceptObjectStorage-Credentials) to access it. If you need to create them, check [Getting Started - Object Storage](https://docs.stackit.cloud/stackit/en/getting-started-objectstorage-71009792.html).
|
|
|
|
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](https://developer.hashicorp.com/terraform/language/settings/backends/s3#configuration).
|
|
<!-- schema generated by tfplugindocs -->
|
|
## Schema
|
|
|
|
### Optional
|
|
|
|
- `authorization_custom_endpoint` (String) Custom endpoint for the Membership service
|
|
- `cdn_custom_endpoint` (String) Custom endpoint for the CDN 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`.
|
|
- `default_region` (String) Region will be used as the default location for regional services. Not all services require a region, some are global
|
|
- `dns_custom_endpoint` (String) Custom endpoint for the DNS service
|
|
- `enable_beta_resources` (Boolean) Enable beta resources. Default is false.
|
|
- `experiments` (List of String) Enables experiments. These are unstable features without official support. More information can be found in the README. Available Experiments: iam, routing-tables, network
|
|
- `git_custom_endpoint` (String) Custom endpoint for the Git service
|
|
- `iaas_custom_endpoint` (String) Custom endpoint for the IaaS service
|
|
- `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
|
|
- `modelserving_custom_endpoint` (String) Custom endpoint for the AI Model Serving service
|
|
- `mongodbflex_custom_endpoint` (String) Custom endpoint for the MongoDB Flex service
|
|
- `objectstorage_custom_endpoint` (String) Custom endpoint for the Object Storage service
|
|
- `observability_custom_endpoint` (String) Custom endpoint for the Observability service
|
|
- `opensearch_custom_endpoint` (String) Custom endpoint for the OpenSearch service
|
|
- `postgresflex_custom_endpoint` (String) Custom endpoint for the PostgresFlex 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, Deprecated) 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
|
|
- `server_backup_custom_endpoint` (String) Custom endpoint for the Server Backup service
|
|
- `server_update_custom_endpoint` (String) Custom endpoint for the Server Update service
|
|
- `service_account_custom_endpoint` (String) Custom endpoint for the Service Account service
|
|
- `service_account_email` (String, Deprecated) 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.
|
|
- `service_enablement_custom_endpoint` (String) Custom endpoint for the Service Enablement API
|
|
- `ske_custom_endpoint` (String) Custom endpoint for the Kubernetes Engine (SKE) service
|
|
- `sqlserverflex_custom_endpoint` (String) Custom endpoint for the SQL Server Flex service
|
|
- `token_custom_endpoint` (String) Custom endpoint for the token API, which is used to request access tokens when using the key flow
|