stackit: Installation & Configuration

Installation

The STACKIT Pulumi Provider (ALPHA) is available as a package in the following Pulumi languages:

• TypeScript: @stackitcloud/pulumi-stackit

Authentication

To authenticate, you will need a service account. Create it in the STACKIT Portal and assign the necessary permissions to it, e.g. project.owner.

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 serviceAccountKeyPath in the provider block

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

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 file should be a JSON and each credential should be set using the name of the respective environment variable, as stated below in each flow. Example:

   {
     "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json"
   }
   

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.

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 Pulumi Provider, additionally to the service account key. Check the STACKIT Knowledge Base for an example of how to create your own key-pair.

To configure the key flow, follow this steps:

1. Create a service account key:

• Use the STACKIT Portal: 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

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:

{
"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: serviceAccountKey or serviceAccountKeyPath
   • setting the environment variable: STACKIT_SERVICE_ACCOUNT_KEY_PATH or STACKIT_SERVICE_ACCOUNT_KEY
     • ensure the set the service account key in STACKIT_SERVICE_ACCOUNT_KEY is correctly formatted. Use e.g. $ export STACKIT_SERVICE_ACCOUNT_KEY=$(cat ./service-account-key.json)
   • 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: privateKey or privateKeyPath
• setting the environment variable: STACKIT_PRIVATE_KEY_PATH or STACKIT_PRIVATE_KEY
• setting STACKIT_PRIVATE_KEY_PATH in the credentials file (see above)

Opting into STACKIT Beta Resources

There are STACKIT resources which are currently in beta which means the API is not stable and can change.

To use such beta resources in the STACKIT Pulumi provider, follow these steps:

1. Provider Configuration Option

   Set the enableBetaResources option in the provider configuration. This is a boolean attribute that can be either true or false. This can be done either in code directly or via the pulumi config command which writes this to a Pulumi.yaml file (e.g. pulumi config set stackit:enableBetaResources true).

   The examples folder provides the information how this can be done in code.

2. Environment Variable

   Set the STACKIT_TF_ENABLE_BETA_RESOURCES environment variable to "true" or "false". Other values will be ignored and will produce a warning.

   export STACKIT_TF_ENABLE_BETA_RESOURCES=true
   

Note: The environment variable takes precedence over the provider configuration option. This means that if the STACKIT_TF_ENABLE_BETA_RESOURCES environment variable is set to a valid value ("true" or "false"), it will override the enableBetaResources option specified in the provider configuration.

Opting into Experiments

Experiments are features that are even less mature and stable than Beta Resources. While there is some assumed stability in beta resources, will have to expect breaking changes while using experimental resources. Experimental Resources do not come with any support or warranty.

To enable experiments set the experiments field in the provider definition e.g. via pulumi config set stackit:experiments [\"routing-tables\"].

Configuration

The following configuration points are available for the stackit provider: