![](<https://www.versio.io/img/partner/stackit.svg>)

# STACKIT importer

Versio.io can import and historize the resources of a STACKIT organization: the folder and project hierarchy and the resources of all projects and regions.

STACKIT offers no single inventory API. The importer reads the projects from the Resource Manager and queries the list API of every supported STACKIT service per project and region. Every resource type becomes its own entity in Versio.io, e.g. `iaas-servers-stackit` or `ske-clusters-stackit`.

## Configuration

You can find the configuration option in Versio.io at `Environment settings > OneImporter > Configurations > STACKIT`.

Here you can edit all existing configurations, create new configurations or delete existing configurations. To add a new configuration, enter a `Name` for your importer and an `Entity suffix` (default: `-stackit`) to clearly identify your STACKIT entities.  
Note that the `Entity suffix` is fixed and cannot be changed afterwards.

Click `Add` to proceed to the configuration.

The following configuration options are available:

| Field | Description | Advice |
| --- | --- | --- |
| **Name** | Meaningful name | Add the word "STACKIT" to identify the importer when viewing the logs |
| **Active** | Option to activate and deactivate the configuration. Data is only imported if the configuration is activated. |  |
| **Credential** | Service account email as username, content of the service account key JSON file as password | See [Set up STACKIT](<#set-up-stackit>) |
| **Organization ID** | ID of your STACKIT organization (optional) | Imports all folders and projects of the organization. Requires the role `Reader` on the organization |
| **Project IDs** | IDs of the projects to import (optional) | Overrides the organization ID. Use it to import selected projects only |
| **Regions** | Regions to import (optional) | Default: `eu01` and `eu02`. Global resources (DNS zones, CDN distributions, service accounts) are always imported |
| **Resource types** | Resource types to import in the format `service.type` (optional) | Leave empty to import all resource types |
| **Executing OneImporter** | Select a Versio.io OneImporter to import the data based on the importer configuration. | Requires an installed OneImporter: [Installation instructions](<https://docs.versio.io/setup-one-importer/index.md>) |
| **Schedule time (cron format)** | Determine the frequency of imports in CRON format | Learn more about CRON format: [https://en.wikipedia.org/wiki/Cron](<https://en.wikipedia.org/wiki/Cron>) |

*Table: STACKIT configuration parameters*

## Set up STACKIT

The importer signs in with a service account key (key flow). It signs a short-lived JWT with the private key from the key file and exchanges it for an access token. The private key never leaves the OneImporter.

The setup takes three steps in STACKIT and two in Versio.io:

1. Create a service account.
2. Create a key for it.
3. Assign the role `Reader`.
4. Store the key as a credential in Versio.io.
5. Configure the importer.

You need permission to create service accounts in a project and to assign roles on the organization or the projects, e.g. the role `Owner`.

### Step 1: Create a service account

1. Open the [STACKIT Portal](<https://portal.stackit.cloud>).
2. Select a project to host the service account, e.g. a project for shared tooling.
3. Go to `IAM and Management > Service accounts` and select `Create service account`.
4. Enter a name, e.g. `versio-io`, and create the service account.
5. Note its email address, e.g. `versio-io-abc123@sa.stackit.cloud`.

> [!NOTE]
>
> A new service account has no permissions, not even in the project that hosts it. Step 3 grants them.

### Step 2: Create a service account key

1. Open the service account and go to `Service Account Keys`.
2. Select `Create service account key` and then `Create new key pair`.
3. Optional: set an expiry date. Note it down: the import stops working when the key expires.
4. Select `Create` and download the JSON file.

> [!WARNING]
>
> STACKIT shows the private key only once. Whoever has the JSON file can access STACKIT as the service account. Do not send it by email or chat.

If you upload your own public key instead, add your private key to the JSON file as `credentials.privateKey`.

### Step 3: Assign the role Reader

The role `Reader` permits reading all resources. It does not permit changes or role assignments.

1. In the STACKIT Portal, open the organization or the project you want to import.
2. Go to `IAM and management > Access` and select `Grant Access`.
3. Enter the email address of the service account from step 1.
4. Select the role `Reader` and save.

Where you assign the role decides what Versio.io can import:

| You want to import | Assign `Reader` on | Enter in the importer |
| --- | --- | --- |
| All folders and projects | The organization | `Organization ID` |
| All projects of a folder | The folder | `Project IDs` of these projects |
| Selected projects | Each project | `Project IDs` |

*Table: Scope of the role Reader*

A role on the organization or a folder applies to all projects below it. New permissions can take a few minutes to take effect.

### Step 4: Store the credential in Versio.io

1. In Versio.io, go to `Environment settings > Credentials` and add a credential, e.g. `STACKIT`.
2. Enter the email address of the service account as username.
3. Open the JSON file from step 2 in a text editor. Copy its complete content and paste it as password.

### Step 5: Configure the importer

1. Go to `Environment settings > OneImporter > Configurations > STACKIT` and add a configuration.
2. Select the credential from step 4.
3. Enter the `Organization ID` or the `Project IDs`, depending on where you assigned the role in step 3.
4. Select the executing OneImporter and save.

You find the IDs in the STACKIT Portal in the settings of the organization or the project. The key file contains the ID of the project that hosts the service account as `projectId`.

### Alternative: set up with the STACKIT CLI

The [STACKIT CLI](<https://docs.stackit.cloud/developer-tools/stackit-cli/usage-examples/>) performs steps 1 to 3:

```bash
stackit service-account create --name versio-io --project-id <project-id>
stackit service-account key create --email <service-account-email>
stackit organization member add <service-account-email> --organization-id <organization-id> --role reader
```

Save the key JSON printed by the second command in a file. It MUST contain only the JSON. To assign the role on a project instead, use `stackit project member add <service-account-email> --project-id <project-id> --role reader`.

### Renew the key

1. Create a new key for the service account as in step 2.
2. Replace the password of the credential in Versio.io with the content of the new JSON file.
3. Wait for a successful import, then delete the old key in the STACKIT Portal.

### Troubleshooting

Check the OneImporter log of the import:

| Log message | Cause | Solution |
| --- | --- | --- |
| `Authentication at STACKIT failed` | The key is invalid, expired or deleted, or the password does not contain the complete JSON file. | Create a new key and store the complete JSON file content as password. |
| `The service account key is no valid JSON` | The password contains only part of the JSON file. | Copy the complete content of the JSON file again. |
| `Reading project ... failed ... lacks the role 'Reader'` | The service account has no role on this project. | Assign `Reader` as in step 3. |
| `No STACKIT project was found` | No organization ID or project IDs are set, or the service account has no role. | Assign `Reader` and enter the organization ID or the project IDs. |
| `'<type>' is not available in N of M project/region combinations` | The service is not enabled or not offered in these projects or regions. This is information, not an error. | Nothing to do. HTTP 403 for a service you use means the service account lacks `Reader` on that project. |

*Table: STACKIT troubleshooting*

## Imported entities

| Entity | Description |
| --- | --- |
| `organization-stackit` | The STACKIT organization |
| `folder-stackit` | Folders of the organization |
| `project-stackit` | Projects |
| `<service>-<type>-stackit` | One entity per resource type, see table below |

*Table: STACKIT entities*

| Service | Resource types |
| --- | --- |
| Compute &amp; network (IaaS) | `iaas-servers`, `iaas-volumes`, `iaas-networks`, `iaas-nics`, `iaas-public-ips`, `iaas-security-groups`, `iaas-images`, `iaas-snapshots`, `iaas-backups`, `iaas-affinity-groups` |
| Kubernetes Engine | `ske-clusters` |
| Load balancing &amp; certificates | `load-balancer-load-balancers`, `alb-load-balancers`, `alb-waf-wafs`, `certificates-certificates` |
| Storage | `object-storage-buckets`, `object-storage-credentials-groups`, `sfs-resource-pools`, `sfs-share-export-policies` |
| Databases | `postgres-flex-instances`, `mongodb-flex-instances`, `sqlserver-flex-instances`, `mariadb-instances`, `opensearch-instances`, `rabbitmq-instances`, `redis-instances`, `valkey-instances`, `logme-instances` |
| Security | `kms-keyrings`, `secrets-manager-instances`, `service-account-service-accounts` |
| Observability &amp; logs | `observability-instances`, `logs-instances` |
| Other | `dns-zones`, `cdn-distributions`, `vpn-gateways`, `registry-artifactories`, `scf-organizations`, `service-enablement-services` |

*Table: STACKIT resource types*

Every resource is related to its project and carries its `projectId` and `region`. Times are stored in UTC milliseconds, sizes in bytes. Projects are related to their folder or organization, folders to their parent folder or organization.

The importer does not read credentials, access keys or passwords of the services.

## Reference

- [STACKIT API documentation](<https://docs.api.stackit.cloud/>)
- [STACKIT API specifications](<https://github.com/stackitcloud/stackit-api-specifications>)
- [STACKIT service account authentication](<https://docs.stackit.cloud/platform/access-and-identity/service-accounts/authentication-flows/>)
- [STACKIT roles and permissions](<https://docs.stackit.cloud/platform/access-and-identity/roles-permissions/roles-permissions/>)
- [STACKIT Portal](<https://portal.stackit.cloud>)
