Skip to content

README.md

Latest commit

 

History

History
215 lines (151 loc) · 12.6 KB

README.md

File metadata and controls

215 lines (151 loc) · 12.6 KB

STACKIT logo

STACKIT Pulumi Provider (BETA)

GitHub License

This repository contains the STACKIT Pulumi Provider.

The STACKIT Pulumi Provider lets you manage STACKIT resources.

This STACKIT Pulumi Provider is in a BETA state. More functionality will be supported soon. Your feedback is appreciated! Feel free to open GitHub issues to provide feature requests and bug reports.

Reporting issues

If you encounter any issues or have suggestions for improvements, please open an issue in the repository or create a ticket in the STACKIT Help Center.

License

Apache 2.0

Installing

This package is available for several languages/platforms:

Node.js (JavaScript/TypeScript)

To use from JavaScript or TypeScript in Node.js, install using either npm:

npm install @stackitcloud/pulumi-stackit

or yarn:

yarn add @stackitcloud/pulumi-stackit

Python

To use from Python, install using pip:

pip install pulumi_stackit

Go

To use from Go, use go get to grab the latest version of the library:

go get github.com/stackitcloud/pulumi-stackit/sdk

.NET

To use from .NET, install using dotnet add package:

dotnet add package 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:

  1. 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"
}
}

  1. 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 Beta Resources

To use 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:experiments [\"routing-tables\"]).

    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 via the same way as seen for beta resources.

Configuration

The following configuration points are available for the stackit provider:

Configuration Variable Environment Variable Description
stackit:authorizationCustomEndpoint STACKIT_AUTHORIZATION_CUSTOM_ENDPOINT Custom endpoint for the Membership service
stackit:cdnCustomEndpoint STACKIT_CDN_CUSTOM_ENDPOINT Custom endpoint for the CDN service
stackit:credentialsPath STACKIT_CREDENTIALS_PATH Path of JSON from where the credentials are read. Default value is ~/.stackit/credentials.json
stackit:defaultRegion STACKIT_DEFAULT_REGION Region will be used as the default location for regional services. Not all services require a region, some are global
stackit:dnsCustomEndpoint STACKIT_DNS_CUSTOM_ENDPOINT Custom endpoint for the DNS service
stackit:enableBetaResources STACKIT_ENABLE_BETA_RESOURCES Enable beta resources. Default is false
stackit:experiments STACKIT_EXPERIMENTS Enables experiments. These are unstable features without official support. Available Experiments: [iam]
stackit:gitCustomEndpoint STACKIT_GIT_CUSTOM_ENDPOINT Custom endpoint for the Git service
stackit:iaasCustomEndpoint STACKIT_IAAS_CUSTOM_ENDPOINT Custom endpoint for the IaaS service
stackit:loadbalancerCustomEndpoint STACKIT_LOADBALANCER_CUSTOM_ENDPOINT Custom endpoint for the Load Balancer service
stackit:logmeCustomEndpoint STACKIT_LOGME_CUSTOM_ENDPOINT Custom endpoint for the LogMe service
stackit:mariadbCustomEndpoint STACKIT_MARIADB_CUSTOM_ENDPOINT Custom endpoint for the MariaDB service
stackit:modelservingCustomEndpoint STACKIT_MODELSERVING_CUSTOM_ENDPOINT Custom endpoint for the AI Model Serving service
stackit:mongodbflexCustomEndpoint STACKIT_MONGODBFLEX_CUSTOM_ENDPOINT Custom endpoint for the MongoDB Flex service
stackit:objectstorageCustomEndpoint STACKIT_OBJECTSTORAGE_CUSTOM_ENDPOINT Custom endpoint for the Object Storage service
stackit:observabilityCustomEndpoint STACKIT_OBSERVABILITY_CUSTOM_ENDPOINT Custom endpoint for the Observability service
stackit:opensearchCustomEndpoint STACKIT_OPENSEARCH_CUSTOM_ENDPOINT Custom endpoint for the OpenSearch service
stackit:postgresflexCustomEndpoint STACKIT_POSTGRESFLEX_CUSTOM_ENDPOINT Custom endpoint for the PostgresFlex service
stackit:privateKey STACKIT_PRIVATE_KEY 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
stackit:privateKeyPath STACKIT_PRIVATE_KEY_PATH 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
stackit:rabbitmqCustomEndpoint STACKIT_RABBITMQ_CUSTOM_ENDPOINT Custom endpoint for the RabbitMQ service
stackit:redisCustomEndpoint STACKIT_REDIS_CUSTOM_ENDPOINT Custom endpoint for the Redis service
stackit:region STACKIT_REGION Region will be used as the default location for regional services. Not all services require a region, some are global ⚠️ Deprecated: This attribute is deprecated. Use 'default_region' instead
stackit:resourcemanagerCustomEndpoint STACKIT_RESOURCEMANAGER_CUSTOM_ENDPOINT Custom endpoint for the Resource Manager service
stackit:secretsmanagerCustomEndpoint STACKIT_SECRETSMANAGER_CUSTOM_ENDPOINT Custom endpoint for the Secrets Manager service
stackit:serverBackupCustomEndpoint STACKIT_SERVER_BACKUP_CUSTOM_ENDPOINT Custom endpoint for the Server Backup service
stackit:serverUpdateCustomEndpoint STACKIT_SERVER_UPDATE_CUSTOM_ENDPOINT Custom endpoint for the Server Update service
stackit:serviceAccountCustomEndpoint STACKIT_SERVICE_ACCOUNT_CUSTOM_ENDPOINT Custom endpoint for the Service Account service
stackit:serviceAccountEmail STACKIT_SERVICE_ACCOUNT_EMAIL Service account email. It is required if you want to use the resource manager project resource ⚠️ Deprecated: The service_account_email field has been deprecated because it is not required. Will be removed after June 12th 2025
stackit:serviceAccountKey STACKIT_SERVICE_ACCOUNT_KEY Service account key used for authentication. If set, the key flow will be used to authenticate all operations
stackit:serviceAccountKeyPath STACKIT_SERVICE_ACCOUNT_KEY_PATH Path for the service account key used for authentication. If set, the key flow will be used to authenticate all operations
stackit:serviceAccountToken STACKIT_SERVICE_ACCOUNT_TOKEN Token used for authentication. If set, the token flow will be used to authenticate all operations
stackit:serviceEnablementCustomEndpoint STACKIT_SERVICE_ENABLEMENT_CUSTOM_ENDPOINT Custom endpoint for the Service Enablement API
stackit:skeCustomEndpoint STACKIT_SKE_CUSTOM_ENDPOINT Custom endpoint for the Kubernetes Engine (SKE) service
stackit:sqlserverflexCustomEndpoint STACKIT_SQLSERVERFLEX_CUSTOM_ENDPOINT Custom endpoint for the SQL Server Flex service
stackit:tokenCustomEndpoint STACKIT_TOKEN_CUSTOM_ENDPOINT Custom endpoint for the token API, which is used to request access tokens when using the key flow

Reference

For detailed reference documentation, please visit the Pulumi registry.