Skip to content

Setup documentation for release #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Fyusel merged 1 commit into from
Dec 5, 2025
Merged

Setup documentation for release #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ jobs:
uses: ./.github/actions/pulumitools
- name: Build sdks
run: make generate_sdks
- name: Lint
- name: Lint provider
run: make lint_provider
- name: Execute tests
run: make test
Expand Down
151 changes: 6 additions & 145 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@
<br>
</div>

# STACKIT Pulumi Provider (BETA)
# STACKIT Pulumi Provider (ALPHA)

[![GitHub License](https://img.shields.io/github/license/stackitcloud/pulumi-stackit)](https://www.apache.org/licenses/LICENSE-2.0)

This repository contains the STACKIT Pulumi Provider.
> [!WARNING]
> This STACKIT Pulumi Provider is in an ALPHA state. Currently, only IaaS and Resource Manager services in TypeScript are supported. More functionality will be supported soon. Your feedback is appreciated! Feel free to open GitHub issues to provide feature requests and bug reports.

The STACKIT Pulumi Provider lets you manage [STACKIT](https://www.stackit.de/en/) 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

Expand Down Expand Up @@ -65,150 +65,11 @@ To use from .NET, install using `dotnet add package`:
dotnet add package Pulumi.stackit
```

## Authentication
## Getting started

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 the necessary permissions to it, e.g. `project.owner`.
A good starting point is the collection of examples in the [Examples](./examples/) folder.

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:

```json
{
"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](https://github.com/stackitcloud/pulumi-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: `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.

```sh
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 |
A detailed authentication guide, information on how to use beta and experimental resources, and available configuration options can be found under [Installation Configuration](./docs/installation-configuration.md).

## Reference

Expand Down
99 changes: 99 additions & 0 deletions docs/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
title: stackit
meta_desc: Learn how to use Pulumi's STACKIT provider to manage STACKIT resources.
layout: package
---

<div align="center">
<br>
<img src=".github/images/stackit-logo.svg" alt="STACKIT logo" width="50%"/>
<br>
<br>
</div>

# STACKIT Pulumi Provider (ALPHA)

[![GitHub License](https://img.shields.io/github/license/stackitcloud/pulumi-stackit)](https://www.apache.org/licenses/LICENSE-2.0)

> [!WARNING]
> This STACKIT Pulumi Provider is in an ALPHA state. Currently, only IaaS and Resource Manager services in TypeScript are supported. More functionality will be supported soon. Your feedback is appreciated! Feel free to open GitHub issues to provide feature requests and bug reports.

The STACKIT Pulumi Provider lets you manage [STACKIT](https://www.stackit.de/en/) resources.


## 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](https://support.stackit.cloud/).

## 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`:

```bash
npm install @stackitcloud/pulumi-stackit
```

or `yarn`:

```bash
yarn add @stackitcloud/pulumi-stackit
```

### Python

To use from Python, install using `pip`:

```bash
pip install pulumi_stackit
```

### Go

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

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

### .NET

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

```bash
dotnet add package Pulumi.stackit
```

## Example

{{< chooser language "typescript" >}}

{{% choosable language typescript %}}

```typescript
import * as pulumi from "@pulumi/pulumi";
import * as stackit from "@stackitcloud/pulumi-stackit";

const exampleWithName = new stackit.Network("example_with_name", {
projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Replace with your actual project ID
name: "example-with-name",
});
```

{{% /choosable %}}
{{< /chooser >}}

For more examples, please have a look at the [Examples](./examples/).

A detailed authentication guide, information on how to use beta and experimental resources, and available configuration options can be found under [Installation Configuration](./docs/installation-configuration.md).

## Reference

For detailed reference documentation, please visit [the Pulumi registry](https://www.pulumi.com/registry/packages/stackit/api-docs/).
Loading
Loading