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:
- Create a service account.
- Create a key for it.
- Assign the role
Reader. - Store the key as a credential in Versio.io.
- 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¶
- Open the STACKIT Portal.
- Select a project to host the service account, e.g. a project for shared tooling.
- Go to
IAM and Management > Service accountsand selectCreate service account. - Enter a name, e.g.
versio-io, and create the service account. - 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¶
- Open the service account and go to
Service Account Keys. - Select
Create service account keyand thenCreate new key pair. - Optional: set an expiry date. Note it down: the import stops working when the key expires.
- Select
Createand 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.
- In the STACKIT Portal, open the organization or the project you want to import.
- Go to
IAM and management > Accessand selectGrant Access. - Enter the email address of the service account from step 1.
- Select the role
Readerand 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¶
- In Versio.io, go to
Environment settings > Credentialsand add a credential, e.g.STACKIT. - Enter the email address of the service account as username.
- 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¶
- Go to
Environment settings > OneImporter > Configurations > STACKITand add a configuration. - Select the credential from step 4.
- Enter the
Organization IDor theProject IDs, depending on where you assigned the role in step 3. - 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¶
- Create a new key for the service account as in step 2.
- Replace the password of the credential in Versio.io with the content of the new JSON file.
- 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.