Developer Tools

Terraform Provider

How to integrate Terraform with Cloudsmith

Cloudsmith is a verified provider on the Terraform Registry.

Installation

To install the Cloudsmith Terraform Provider, add the following to the required_providers in your Terraform module:

  required_providers {
    cloudsmith = {
      source = "cloudsmith-io/cloudsmith"
      version = "0.0.5"
    }
  }

You also need to add your Cloudsmith API Key, for use by the provider:

provider "cloudsmith" {
    api_key = "API-KEY"
}

You then run terraform init and Terraform will automatically install the provider. To specify a particular provider version when installing providers, see the Terraform documentation on provider versioning.

Data Sources

namespace

The namespace data source allows fetching of metadata about a given Cloudsmith namespace. The fetched data can be used to resolve permanent identifiers from a namespace's user-facing name. These identifiers can then be passed to other resources to allow more consistent identification as user-facing names can change.

data "cloudsmith_namespace" "my_namespace" {
    slug = "my-namespace"
}

Resources

repository

The repository resource allows the creation and management of package repositories within a Cloudsmith namespace. Repositories store packages and are the main entities with which Cloudsmith users interact.

resource "cloudsmith_repository" "my_repository" {
    name        = "My Repository"
    namespace   = "${data.cloudsmith_namespace.my_namespace.slug_perm}"
    description = "A certifiably-awesome private package repository"
}

See the repository documentation for more information on creating and managing repositories.

Repository privileges

The repository privileges resource allows the management of privileges for a given Cloudsmith repository. Using this resource it is possible to assign users, teams, or service accounts to a repository, and define the appropriate permission level for each.

Note that while users can be added to repositories in this manner, since Terraform does not manage those user accounts, you may encounter issues if the users change or are deleted outside of Terraform.

resource "cloudsmith_repository_privileges" "privs" {
    organization = data.cloudsmith_organization.my_organization.slug
    repository   = cloudsmith_repository.my_repository.slug

    service {
        privilege = "Write"
        slug      = cloudsmith_service.my_service.slug
    }

    team {
        privilege = "Write"
        slug      = cloudsmith_team.my_team.slug
    }

    team {
        privilege = "Read"
        slug      = cloudsmith_team.my_other_team.slug
    }

    user {
        privilege = "Read"
        slug      = "some-user-slug"
    }
}

When creating a repository via Terraform using a service account and subsequently adjusting the privileges on that same repository, ensure to include a block giving the provisioning account the 'Admin' privilege (as it would get by default by being the creator). This will ensure that the account can continue to provision resources (e.g. entitlements). Otherwise, the resource may overwrite that privilege and further provisioning on the repository when using that account would fail.

Entitlement

The entitlement resource allows the creation and management of Entitlement tokens for a Cloudsmith repository. Entitlement tokens grant read-only access to a repository and can be configured with a number of custom restrictions if necessary.

resource "cloudsmith_entitlement" "my_entitlement" {
    name       = "Entitlement Token 1"
    namespace  = "${cloudsmith_repository.test.namespace}"
    repository = "${cloudsmith_repository.test.slug_perm}"
}

Please see the Entitlements documentation for more details on managing entitlement tokens and restrictions.

EPM policies

Early Access

Enterprise Policy Manager (EPM) is in early access. If you would like to try this feature, please contact us.

You can manage EPM policies by using the following resources and data sources:

To learn more about Cloudsmith EPM, see Enterprise Policy Manager.

See the EPM policy example in the terraform-provider-cloudsmith GitHub repository for a worked example of a Terraform module that uses the Cloudsmith provider to create:

• A quarantine-on-missing-tag policy
• A tag cleanup policy
• A cooldown policy

Connected repositories

Early Access

Connected repositories are in early access (EA) and are currently supported for Maven, Docker, Python, NPM, Go, Cargo (Rust), NuGet, Helm, Conan, and Conda. Please contact us if you are interested in trying them.

You can manage connected repositories from the Terraform provider by using the cloudsmith_repository_connected resource and the cloudsmith_repository_connected_list data source.

For more information about connected repositories in Cloudsmith, see Connected repositories.

Example Module

A complete, but minimal, example of a Terraform module that uses the Cloudsmith Provider to create a repository and an Entitlement Token (with some basic token restrictions) is:

terraform {
  required_providers {
    cloudsmith = {
      source = "cloudsmith-io/cloudsmith"
      version = "0.0.5"
    }
  }
}

provider "cloudsmith" {
    api_key = "abcdefghijlkl1234567890"
}

data "cloudsmith_namespace" "demo-organization {
    slug = "demo-org"
}

resource "cloudsmith_repository" "terraform-demo" {
    description = "Example repo provisioned by Terraform"
    name        = "Terraform Demo"
    namespace   = "${data.cloudsmith_namespace.demo.slug_perm}"
    slug        = "terraform-demo"
    repository_type   = "Private"
}

resource "cloudsmith_entitlement" "demo-entitlement" {
    name       = "Token 1"
    namespace  = "${cloudsmith_repository.terraform-demo.namespace}"
    repository = "${cloudsmith_repository.terraform-demo.slug_perm}"
    limit_num_downloads = "15"
    limit_num_clients ="1"
    limit_package_query = "name:,my-package"
}

More example modules

Further examples can be found on github in our terraform-provider

Updated 2 weeks ago