Skip to content

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
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
Schedule time (cron format) Determine the frequency of imports in CRON format Learn more about CRON format: 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.
  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 performs steps 1 to 3:

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 & 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 & 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 & 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