Overview

Overview

A Cloud Account allows you to store credentials for cloud infrastructure which the Platform Orchestrator needs to connect to at a central place in your Humanitec Organization.

Configured Cloud Accounts can then be referenced in Resource Definitions to connect to cloud resources, removing the need to maintain those credentials for every single Resource Definition. Use the driver_account element to reference a Cloud Account:

apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: my-resource-definition
entity:
  # The driver_account references a Cloud Account configured in the Platform Orchestrator.
  driver_account: my-cloud-account
  ...

See the Account References section below for a flexible way to share Cloud Account references across Resource Definitions.

In order to use a Cloud Account, the Driver being used in the Resource Definition needs to support the respective account type. For example, a “Google Cloud” (GCP) Account can be used by the MariaDB Cloud SQL Driver because that Driver supports gcp in its account types. Likewise, an “Amazon Web Services” (AWS) Account can be used by the AWS Route53 Driver which supports aws in its account types.

“In use”

Whenever a Cloud Account is referenced by a non-deleted Resource Definition or by an Active Resource , that Cloud Account is considered to be “in use”.

The Cloud Account cannot be deleted until all references are removed. The Platform Orchestrator will output the referencing elements for a failed deletion.

Temporary vs static credentials

Each Cloud Account type supports either temporary or static credentials.

Temporary credentials are relatively short-lived credentials often created on-the-fly and based on a previously established trust relationship between the involved parties. Because they expire quickly, they pose much less of a risk when breached, and therefore provide superior security when compared to static credentials. They also reduce maintenance effort because they don’t need to be renewed.

Static credentials are relatively long-lived credentials created by some administrative entity and then distributed to its users. Because they can be exploited extensively when breached, they pose a much higher risk than temporary credentials. Unless valid indefinitely, which is not recommended, they also require maintenance effort for renewing (rotating) them.

Account References

You may use a reference to another Resource Definition in the driver_account instead of a Cloud Account name. Your Resource Definition will then use the Cloud Account of the referenced Resource. Use the .account Placeholder to specify an Account Reference. It is available in the driver_account item only.

driver_account: ${resources['type.class#id'].account}

This Account Reference will match a config type Resource of class default with the id aws-account:

driver_account: ${resources['config.default#aws-account'].account}

A common use case is to use different Cloud Accounts for different Environments. To use different accounts, you would normally need to create a separate Resource Definition for each of them, even if the Resource Definition parameters (except the driver_account) are identical. Account referencing lets you use the same Resource Definition for all Environments by referencing an account from another Resource Definition, commonly of type config as shown above, which is Environment specific per its matching criteria .

Go to this extended example to see Account References applied in practice.

Manage Cloud Accounts

You need the Administrator role in the Organization to manage Cloud Accounts.

Create Cloud Accounts

The creation process for a Cloud Account varies greatly by account type. Refer to the dedicated page for your target cloud:

View Cloud Accounts

View the Cloud Accounts configured in your Organization. Note that the output will never expose the secret properties of a Cloud Account.

Select Cloud Accounts from the main navigation.

Use the humctl get resource-account command to view Cloud Accounts. Add the flag -o yaml or -o json for a detailed output.

# View all Cloud Accounts in an Organization
humctl get resource-account

# View a specific Cloud Account by its id
humctl get resource-account my-cloud-account


# View all Cloud Accounts in an Organization
curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/accounts" \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"

# View a specific Cloud Account by its id
curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/accounts/my-account" \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with the Admin role on the Organization
HUMANITEC_ORG my-org The Humanitec organization the Application is in

Inspect your Terraform state for resources of type humanitec_resource_account .

Delete Cloud Accounts

Delete Cloud Accounts configured in your Organization.

Whenever a Cloud Account is referenced by a non-deleted Resource Definition or by an Active Resource , that Cloud Account is considered to be “in use”.

The Cloud Account cannot be deleted until all references are removed. The Platform Orchestrator will output the referencing elements for a failed deletion.

Select Cloud Accounts from the main navigation. Click the trash icon for a Cloud Account and confirm its deletion.

Use the humctl delete resource-account command to delete Cloud Accounts.

# Delete a specific Cloud Account by its id
humctl delete resource-account my-cloud-account


# Delete a specific Cloud Account by its id
curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/accounts/my-account" \
  -X DELETE \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json"

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with the Admin role on the Organization
HUMANITEC_ORG my-org The Humanitec organization the Application is in

Remove the resources of type humanitec_resource_account from your Terraform Code and perform a terraform apply, or perform a terraform destroy.

Test Cloud Accounts

The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account.

Select Cloud Accounts from the main navigation. Click the “Test” button on a Cloud Account and confirm the test execution.

The check operation can be called using this CLI command.

humctl resources check-account ${CLOUD_ACCOUNT_ID}

The check operation can be called using this API endpoint .

curl https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/accounts/${CLOUD_ACCOUNT_ID}/actions/check \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json"

AWS