Deployments.ai Docs

OpenTofu provider

Issue an environment API key from OpenTofu and deliver it to AWS Parameter Store without putting the key in state.

The Deployments.ai OpenTofu provider manages one resource, deployments_environment_credential. The resource makes sure a named service account and API key exist in one environment, then writes the key to an AWS Systems Manager Parameter Store SecureString parameter. OpenTofu state keeps identifiers only, never the key. Use it to give a service that you deploy with OpenTofu its platform credential.

To keep the same kind of credential outside OpenTofu, use the credential tool's api-key command. It applies the same rules, keeps a working key across runs, and can also mint the bearer that manages the key from an operator identity.

Availability

The provider is not published to a registry. You build it from infrastructure/terraform-provider-deployments and install it under the local address terraform.local/deployments-ai/deployments, version 0.1.0. It has one resource and no data sources. Its default API URL is https://api.deployments.ai, so set api_url to your installation's API origin.

Install the provider

The build needs Go. From the repository root, run:

cd infrastructure/terraform-provider-deployments
make install

make install builds the terraform-provider-deployments binary and copies it to ~/.terraform.d/plugins/terraform.local/deployments-ai/deployments/0.1.0/<os>_<arch>/, a local plugin directory that tofu init searches. Set VERSION to install under another version.

Then require the provider in your configuration:

terraform {
  required_providers {
    deployments = {
      source  = "terraform.local/deployments-ai/deployments"
      version = "0.1.0"
    }
  }
}

Configure the provider

Each attribute falls back to environment variables when you leave it out of the provider block.

AttributeEnvironment fallbackDefault
api_keyDEPLOYMENTS_API_KEYNone. Required.
api_urlDEPLOYMENTS_API_URLhttps://api.deployments.ai
organization_idDEPLOYMENTS_ORGANIZATION_ID, then DEPLOYMENTS_ORGNone. Required.
project_idDEPLOYMENTS_PROJECT_ID, then DEPLOYMENTS_PROJECTNone. Required.
environment_idDEPLOYMENTS_ENVIRONMENT_ID, then DEPLOYMENTS_ENVIRONMENTNone. Required.
aws_regionAWS_REGION, then AWS_DEFAULT_REGIONus-east-2

api_key is sensitive. api_url must be an origin with no path, query, or fragment. The provider reads AWS credentials from the AWS SDK default chain and uses aws_region for Parameter Store.

The provider sends organization_id, project_id, and environment_id as the x-deployments-organization, x-deployments-project, and x-deployments-environment headers on every request, and a new idempotency-key on every write. Use an API key that belongs to that environment and holds the scopes to manage service accounts and API keys. A caller can grant only scopes it holds, so the key also needs every scope you put in scopes. See Service accounts and API keys.

provider "deployments" {
  api_url         = "https://api.example.com"
  organization_id = "org_123"
  project_id      = "proj_123"
  environment_id  = "env_123"
}

Issue a credential

Point the credential at a Parameter Store path. Do not declare the parameter with aws_ssm_parameter: that resource reads the value back into state. The provider creates the parameter on first write.

resource "deployments_environment_credential" "worker" {
  name        = "worker"
  scopes      = ["agents:read", "runs:write"]
  secret_name = "/worker/platform-api-key"
}

After tofu apply, the parameter's current version holds the API key as a SecureString encrypted with the AWS managed key. Your service reads it with ssm:GetParameter and decryption.

Arguments and attributes

NameKindMeaning
nameRequired. Forces replacement.The name of both the service account and the API key.
scopesRequired. Forces replacement.The capability scopes for both the service account and the API key.
secret_nameRequired. Forces replacement.The Parameter Store parameter name that receives the key.
idComputed<service_account_id>/<api_credential_id>
service_account_idComputedThe service account ID.
api_credential_idComputedThe API key ID.
key_prefixComputedThe key's display prefix.
secret_arnComputedThe ARN of the parameter.
secret_version_idComputedThe parameter version that holds the key.

What the provider does

On create, the provider runs these steps in order:

  1. It lists the environment's service accounts and looks for an active one named name. If it finds one with different scopes, it fails with "refusing to widen it". If it finds none, it creates one with scopes.
  2. It reads the parameter. A missing parameter counts as empty.
  3. If the parameter already holds an active key for this service account and name, it keeps that key. If that key's scopes differ from scopes, it fails with "refusing to widen it".
  4. Otherwise it issues a new API key and checks that the key authenticates with one GET request. Then it writes the key to the parameter, creating it or adding a new version.

The check in step 4 uses the first of these scopes that scopes contains. If scopes contains none of them, create fails, so include at least one.

ScopeRequest
approvals:readGET /v1/approvals?limit=1
agents:readGET /v1/agent-definitions?limit=1
channels:readGET /v1/channel-bindings?limit=1
workspaces:readGET /v1/workspaces?limit=1
tools:readGET /v1/extensions?limit=1
schedules:readGET /v1/schedules?limit=1
webhooks:readGET /v1/webhooks?limit=1

If the check fails, the provider reports the error and does not write the parameter. The key it just issued stays active, so revoke it with deployments api-key revoke.

Refresh, change, and delete

  • Refresh. The provider looks up the API key by ID and reads the parameter. If the key is missing or no longer active, or the parameter is gone, it removes the resource from state, and the next apply creates it again. Otherwise it refreshes key_prefix, secret_arn, and secret_version_id.
  • Change. The resource has no in-place update. A change to name, scopes, or secret_name replaces it. If you change scopes and keep name, the replacement fails on create, because delete leaves the service account with its old scopes.
  • Delete. The provider revokes the API key. It leaves the service account active and leaves the parameter and its last value in place. Revoking a key that is already gone succeeds.

By default OpenTofu destroys the old resource before it creates the replacement. During a replacement, the old key stops working before the new key reaches the parameter.

Move from Secrets Manager

Releases before Parameter Store wrote the key to a Secrets Manager secret, and their state holds that secret's name. Copy the key to the new parameter, then change secret_name to the parameter path and apply:

value="$(aws secretsmanager get-secret-value --secret-id <old_secret_name> --query SecretString --output text)"
printf %s "${value}" | aws ssm put-parameter --name <parameter_name> --type SecureString --value file:///dev/stdin
unset value

On refresh, the provider forgets a resource whose secret_name is not a parameter path. It does not revoke the key. The create that follows finds the copied key in the parameter and keeps it. If you skip the copy, the create issues a new key and the old one stays active until you revoke it. Delete the old secret after the service reads the parameter.

Import an existing credential

The import ID is the service account ID, the API key ID, and the parameter name, separated by commas:

tofu import deployments_environment_credential.worker <service_account_id>,<api_credential_id>,<parameter_name>

Reference

On this page