diff --git a/.github/workflows/copy-cloud-docs-for-tfe.yml b/.github/workflows/copy-cloud-docs-for-tfe.yml index ad2d10f58e..2ee6a005aa 100644 --- a/.github/workflows/copy-cloud-docs-for-tfe.yml +++ b/.github/workflows/copy-cloud-docs-for-tfe.yml @@ -4,7 +4,7 @@ on: workflow_dispatch: inputs: branch: - description: 'Ex: docs-tfe-releases/v123456-1; ptfe-releases/v123456-1' + description: 'Release branch. (Ex: docs-tfe-releases/v123456-1, ptfe-releases/v123456-1)' required: true env: @@ -69,51 +69,41 @@ jobs: uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 with: ref: ${{env.release_branch}} - path: "${{github.workspace}}/release" + path: '${{github.workspace}}/release' - - name: Checkout main for new docs version ACTUAL PR + # MAKE THE RELEASE PR + - name: Checkout main for new docs version RELEASE PR uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 with: - path: "${{github.workspace}}/new-docs-pr" - - - name: Checkout main for new docs version DIFF PR - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 - with: - path: "${{github.workspace}}/new-docs-diff-pr" + path: '${{github.workspace}}/new-docs-pr' - name: Generate version-metadata for workflow - working-directory: "${{github.workspace}}/release" + working-directory: '${{github.workspace}}/release' run: | npm i npm run prebuild-only-version-metadata - # MAKING THE DIFF PR - - name: Copy files for new docs version DIFF PR - uses: ./release/.github/actions/copy-cloud-docs-for-tfe - with: - source_path: "${{github.workspace}}/release" - target_path: "${{github.workspace}}/new-docs-diff-pr" + - name: Create the new TFE version folder for RELEASE PR + run: | + version=$(jq -r '.["terraform-enterprise"][] | select(.isLatest == true) | .version' "${{github.workspace}}/release/app/api/versionMetadata.json") + echo "Latest terraform-enterprise version: ${version}" + echo "LATEST_TFE_VERSION=$version" >> $GITHUB_ENV + + mkdir -p "${{github.workspace}}/new-docs-pr/content/terraform-enterprise/${{env.SERIES}}-${{env.RELEASE}}" + + cp -a "${{github.workspace}}/release/content/terraform-enterprise/${version}" "${{github.workspace}}/new-docs-pr/content/terraform-enterprise/${{env.SERIES}}-${{env.RELEASE}}" - - name: Open new docs docs version DIFF PR - working-directory: "${{github.workspace}}/new-docs-diff-pr" + - name: Open new docs version RELEASE PR + working-directory: '${{github.workspace}}/new-docs-pr' env: - branch_name: docs-diff/${{env.SERIES}}-${{env.RELEASE}} + branch_name: docs/${{env.SERIES}}-${{env.RELEASE}} pr_body: | - # Automated Docs DIFF PR for TFE ${{env.SERIES}}-${{env.RELEASE}} - - **❗ DO NOT MERGE THIS PR, IT IS FOR DIFFS ONLY ❗** + # Automated Docs Release PR for TFE ${{env.SERIES}}-${{env.RELEASE}} **TFE Series**: ${{ env.SERIES }} **TFE Release**: ${{ env.RELEASE }} - This copies over `cloud-docs` from: - - ${{github.server_url}}/${{github.repository}}/tree/${{env.release_branch}} - - This PR was created via: - - ${{github.server_url}}/${{github.repository}}/actions/runs/${{github.run_id}} - - Triggered by creation of branch: - - ${{github.server_url}}/${{github.repository}}/tree/${{env.release_branch}} + ...Waiting for the diff PR to be created, before finishing this PR's description... # secrets.WORKFLOW_TESTING_TOKEN requires permissions read:org, repo, workflow run: | @@ -132,38 +122,40 @@ jobs: git checkout -b ${{env.branch_name}} git add . - git commit -m "Automated Docs DIFF PR" --no-verify + git commit -m "Automated Release Docs PR" --no-verify git push origin HEAD gh pr create \ --body="${{env.pr_body}}" \ - --title="Automated Docs DIFF PR for TFE ${{env.SERIES}}-${{env.RELEASE}}" \ + --title="Automated Docs Release PR for TFE ${{env.SERIES}}-${{env.RELEASE}}" \ --draft \ --head ${{env.branch_name}} \ --base main - diff_pr_url=$(gh pr view --json url --jq '.url') - echo "DIFF_PR_URL=${diff_pr_url}" >> $GITHUB_ENV - echo "**Automated DIFF PR URL**: ${diff_pr_url}" >> $GITHUB_STEP_SUMMARY - - echo "(Closed DIFF PR at ${diff_pr_url} in order to prevent an accidental merge)" >> $GITHUB_STEP_SUMMARY - gh pr close "${diff_pr_url}" + pr_url=$(gh pr view --json url --jq '.url') + echo "PR_URL=${pr_url}" >> $GITHUB_ENV + echo "**Automated Release PR URL**: ${pr_url}" >> $GITHUB_STEP_SUMMARY + # MAKE THE DIFF PR + - name: Checkout main for new docs version DIFF PR + uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 + with: + path: '${{github.workspace}}/new-docs-diff-pr' - # MAKING THE ACTUAL PR - - name: Copy files for new docs version ACTUAL PR + - name: Copy files for new docs version DIFF PR uses: ./release/.github/actions/copy-cloud-docs-for-tfe with: - source_path: "${{github.workspace}}/release" - target_path: "${{github.workspace}}/new-docs-pr" + source_path: '${{github.workspace}}/release' + target_path: '${{github.workspace}}/new-docs-diff-pr' new_TFE_version: ${{env.SERIES}}-${{env.RELEASE}} - - name: Open new docs version ACTUAL PR - working-directory: "${{github.workspace}}/new-docs-pr" + - name: Open new docs version DIFF PR + working-directory: '${{github.workspace}}/new-docs-diff-pr' env: - branch_name: docs/${{env.SERIES}}-${{env.RELEASE}} + release_branch_name: docs/${{env.SERIES}}-${{env.RELEASE}} + branch_name: docs-diff/${{env.SERIES}}-${{env.RELEASE}} pr_body: | - # Automated Docs PR for TFE ${{env.SERIES}}-${{env.RELEASE}} + # Automated Docs Diff PR for TFE ${{env.SERIES}}-${{env.RELEASE}} **TFE Series**: ${{ env.SERIES }} **TFE Release**: ${{ env.RELEASE }} @@ -177,15 +169,8 @@ jobs: Triggered by creation of branch: - ${{github.server_url}}/${{github.repository}}/tree/${{env.release_branch}} - Changes against the current TFE docs: - - ${{ env.DIFF_PR_URL }} - - ### Reviewers - - > **Note**: The `digital-content-events` GH App currently does not have permissions to request PR reviews from teams. - - - [ ] @hashicorp/ptfe-review - - [ ] @hashicorp/web-platform + Merges into the new docs release version branch: + - ${{ env.PR_URL }} # secrets.WORKFLOW_TESTING_TOKEN requires permissions read:org, repo, workflow run: | @@ -204,16 +189,48 @@ jobs: git checkout -b ${{env.branch_name}} git add . - git commit -m "Automated Docs PR" --no-verify + git commit -m "Automated Docs Diff PR" --no-verify git push origin HEAD gh pr create \ --body="${{env.pr_body}}" \ - --title="Automated Docs PR for TFE ${{env.SERIES}}-${{env.RELEASE}}" \ + --title="Automated Docs Diff PR for TFE ${{env.SERIES}}-${{env.RELEASE}}" \ --draft \ --head ${{env.branch_name}} \ - --base main + --base ${{env.release_branch_name}} - pr_url=$(gh pr view --json url --jq '.url') - echo "PR_URL=${pr_url}" >> $GITHUB_ENV - echo "**Automated ACTUAL PR URL**: ${pr_url}" >> $GITHUB_STEP_SUMMARY + diff_pr_url=$(gh pr view --json url --jq '.url') + echo "DIFF_PR_URL=${diff_pr_url}" >> $GITHUB_ENV + echo "**Automated DIFF PR URL**: ${diff_pr_url}" >> $GITHUB_STEP_SUMMARY + + - name: Update RELEASE PR with DIFF PR URL + env: + branch_name: docs/${{env.SERIES}}-${{env.RELEASE}} + pr_body: | + # Automated Docs Release PR for TFE ${{env.SERIES}}-${{env.RELEASE}} + + **TFE Series**: ${{ env.SERIES }} + **TFE Release**: ${{ env.RELEASE }} + + This PR was created via: + - ${{github.server_url}}/${{github.repository}}/actions/runs/${{github.run_id}} + + Triggered by creation of branch: + - ${{github.server_url}}/${{github.repository}}/tree/${{env.release_branch}} + + Changes against the current TFE docs: + - ${{ env.DIFF_PR_URL }} + + ### Reviewers + + > **Note**: The `digital-content-events` GH App currently does not have permissions to request PR reviews from teams. + + - [ ] @hashicorp/ptfe-review + - [ ] @hashicorp/web-platform + run: | + echo ${{ secrets.WORKFLOW_TESTING_TOKEN }} | gh auth login --with-token + git config --global user.email "team-rel-eng@hashicorp.com" + git config --global user.name "tfe-release-bot" + + gh pr update ${{env.PR_URL}} \ + --body="${{env.pr_body}}" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/data/.gitkeep b/content/terraform-enterprise/v000011-1/v202504-1/data/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/content/terraform-enterprise/v000011-1/v202504-1/data/enterprise-nav-data.json b/content/terraform-enterprise/v000011-1/v202504-1/data/enterprise-nav-data.json new file mode 100644 index 0000000000..d12ca760d0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/data/enterprise-nav-data.json @@ -0,0 +1,1486 @@ +[ + { "heading": "Terraform Enterprise" }, + { "title": "Overview", "path": "" }, + { + "title": "API", + "routes": [ + { + "title": "API Docs template", + "path": "api-docs/_template", + "hidden": true + }, + { "title": "Overview", "path": "api-docs" }, + { "title": "Account", "path": "api-docs/account" }, + { + "title": "Admin", + "routes": [ + { "title": "Overview", "path": "api-docs/admin" }, + { + "title": "Registry Sharing", + "path": "api-docs/admin/registry-sharing" + }, + { + "title": "Module Sharing", + "path": "api-docs/admin/module-sharing" + }, + { + "title": "Organizations", + "path": "api-docs/admin/organizations" + }, + { "title": "Runs", "path": "api-docs/admin/runs" }, + { + "title": "Settings", + "path": "api-docs/admin/settings" + }, + { + "title": "Terraform Versions", + "path": "api-docs/admin/terraform-versions" + }, + { + "title": "OPA Versions", + "path": "api-docs/admin/opa-versions" + }, + { + "title": "Sentinel Versions", + "path": "api-docs/admin/sentinel-versions" + }, + { "title": "Users", "path": "api-docs/admin/users" }, + { "title": "Initial Admin User", "path": "api-docs/admin/initial-admin-user" }, + { + "title": "Workspaces", + "path": "api-docs/admin/workspaces" + } + ] + }, + { + "title": "Agent Pools", + "path": "api-docs/agents" + }, + { "title": "Agent Tokens", "path": "api-docs/agent-tokens" }, + { "title": "Applies", "path": "api-docs/applies" }, + { "title": "Assessment Results", "path": "api-docs/assessment-results" }, + { + "title": "Comments", + "path": "api-docs/comments" + }, + { + "title": "Configuration Versions", + "path": "api-docs/configuration-versions" + }, + { + "title": "Cost Estimates", + "path": "api-docs/cost-estimates" + }, + { "title": "Data Retention Policies", "path": "api-docs/data-retention-policies" }, + { + "title": "GitHub App Installations", + "path": "api-docs/github-app-installations" + }, + { + "title": "Notification Configurations", + "path": "api-docs/notification-configurations" + }, + { + "title": "No-Code Provisioning", + "path": "api-docs/no-code-provisioning" + }, + { "title": "OAuth Clients", "path": "api-docs/oauth-clients" }, + { "title": "OAuth Tokens", "path": "api-docs/oauth-tokens" }, + { "title": "Organizations", "path": "api-docs/organizations" }, + { + "title": "Organization Memberships", + "path": "api-docs/organization-memberships" + }, + { + "title": "Organization Tags", + "path": "api-docs/organization-tags" + }, + { + "title": "Organization Tokens", + "path": "api-docs/organization-tokens" + }, + { "title": "Plan Exports", "path": "api-docs/plan-exports" }, + { "title": "Plans", "path": "api-docs/plans" }, + { "title": "Policies", "path": "api-docs/policies" }, + { "title": "Policy Checks", "path": "api-docs/policy-checks" }, + { + "title": "Policy Evaluations", + "path": "api-docs/policy-evaluations" + }, + { "title": "Policy Sets", "path": "api-docs/policy-sets" }, + { + "title": "Policy Set Parameters", + "path": "api-docs/policy-set-params" + }, + { + "title": "Private Registry", + "routes": [ + { "title": "Modules", "path": "api-docs/private-registry/modules" }, + { "title": "Manage Module Versions", "path": "api-docs/private-registry/manage-module-versions" }, + { + "title": "Providers", + "path": "api-docs/private-registry/providers" + }, + { + "title": "Private Provider Versions and Platforms", + "path": "api-docs/private-registry/provider-versions-platforms" + }, + { "title": "GPG Keys", "path": "api-docs/private-registry/gpg-keys" }, + { + "title": "Tests", + "path": "api-docs/private-registry/tests" + } + ] + }, + { "title": "Projects", "path": "api-docs/projects" }, + { + "title": "Project Team Access", + "path": "api-docs/project-team-access" + }, + { "title": "Reserved Tag Keys", "path": "api-docs/reserved-tag-keys"}, + { "title": "Runs", "path": "api-docs/run" }, + { + "title": "Run Tasks", + "routes": [ + { "title": "Run Tasks", "path": "api-docs/run-tasks/run-tasks" }, + { + "title": "Stages and Results", + "path": "api-docs/run-tasks/run-task-stages-and-results" + }, + { + "title": "Custom Integration", + "path": "api-docs/run-tasks/run-tasks-integration" + } + ] + }, + { "title": "Run Triggers", "path": "api-docs/run-triggers" }, + { "title": "SSH Keys", "path": "api-docs/ssh-keys" }, + { + "title": "State Versions", + "path": "api-docs/state-versions" + }, + { + "title": "State Version Outputs", + "path": "api-docs/state-version-outputs" + }, + { "title": "Team Access", "path": "api-docs/team-access" }, + { "title": "Team Membership", "path": "api-docs/team-members" }, + { "title": "Team Tokens", "path": "api-docs/team-tokens" }, + { "title": "Teams", "path": "api-docs/teams" }, + { "title": "User Tokens", "path": "api-docs/user-tokens" }, + { "title": "Users", "path": "api-docs/users" }, + { "title": "Variables", "path": "api-docs/variables" }, + { "title": "VCS Events", "path": "api-docs/vcs-events" }, + { "title": "Workspaces", "path": "api-docs/workspaces" }, + { + "title": "Workspace-Specific Variables", + "path": "api-docs/workspace-variables" + }, + { + "title": "Workspace Resources", + "path": "api-docs/workspace-resources" + }, + { + "title": "Variable Sets", + "path": "api-docs/variable-sets" + }, + { + "title": "Changelog", + "path": "api-docs/changelog" + }, + { + "title": "Stability Policy", + "path": "api-docs/stability-policy" + } + ] + }, + { + "title": "Deploy Terraform Enterprise", + "routes": [ + { "title": "Overview", "path": "deploy" }, + { + "title": "Migrate to a non-Replicated runtime", + "path": "deploy/replicated-migration" + }, + { + "title": "Prepare host environment", + "path": "deploy/prepare-host" + }, + { + "title": "Create deployment configuration", + "routes": [ + { + "title": "Overview", + "path": "deploy/configuration" + }, + { + "title": "Configure a license", + "path": "deploy/configuration/license" + }, + { + "title": "Configure network access", + "path": "deploy/configuration/network" + }, + { + "title": "Configure data storage", + "routes": [ + { + "title": "Overview", + "path": "deploy/configuration/storage" + }, + { + "title": "Configure operational mode", + "path": "deploy/configuration/storage/configure-mode" + }, + { + "title": "Configure object storage", + "path": "deploy/configuration/storage/connect-object" + }, + { + "title": "Configure database connection", + "routes": [ + { + "title": "Overview", + "path": "deploy/configuration/storage/connect-database" + }, + { + "title": "Connect to PostgreSQL", + "path": "deploy/configuration/storage/connect-database/postgres" + }, + { + "title": "Connect to a PostgreSQL cluster BETA", + "path": "deploy/configuration/storage/connect-database/postgres-cluster" + }, + { + "title": "Connect to a PostgreSQL cluster deployed with Patroni BETA", + "path": "deploy/configuration/storage/connect-database/patroni" + }, + { + "title": "Connect to a PostgreSQL cluster deployed with Aurora BETA", + "path": "deploy/configuration/storage/connect-database/aurora" + }, + { + "title": "Measure database failover resilience BETA", + "path": "deploy/configuration/storage/connect-database/failover-resilience" + } + ] + }, + { + "title": "Configure Redis connection", + "path": "deploy/configuration/storage/connect-redis" + }, + { + "title": "Configure external Vault connection", + "path": "deploy/configuration/storage/connect-vault" + } + ] + } + ] + }, + { + "title": "Deploy to Nomad", + "path": "deploy/nomad" + }, + { + "title": "Deploy to Kubernetes", + "routes": [ + { + "title": "Install Terraform Enterprise", + "path": "deploy/kubernetes" + }, + { + "title": "Scale up your Kubernetes deployment", + "routes": [ + { + "title": "Overview", + "path": "deploy/kubernetes/scale" + }, + { + "title": "Increase replicas", + "path": "deploy/kubernetes/scale/replicas" + }, + { + "title": "Increase run capacity", + "path": "deploy/kubernetes/scale/run-capacity" + } + + ] + } + ] + }, + { + "title": "Deploy to OpenShift", + "path": "deploy/openshift" + }, + { + "title": "Deploy to Podman", + "path": "deploy/podman" + }, + { + "title": "Deploy to Docker", + "routes": [ + { + "title": "Install Terraform Enterprise", + "path": "deploy/docker" + }, + { + "title": "Scale up your Docker deployment", + "path": "deploy/docker/scale" + } + ] + }, + { + "title": "Deploy to Replicated DEPRECATED", + "routes": [ + { "title": "Overview", "path": "deploy/replicated" }, + { + "title": "Requirements", + "routes": [ + { + "title": "Credentials", + "path": "deploy/replicated/requirements/credentials" + }, + { + "title": "Hardware", + "path": "deploy/replicated/requirements/hardware" + }, + { + "title": "Operating System", + "routes": [ + { + "title": "Supported OS", + "path": "deploy/replicated/requirements/os-specific/supported-os" + }, + { + "title": "RedHat Linux", + "path": "deploy/replicated/requirements/os-specific/rhel-requirements" + }, + { + "title": "CentOS Linux", + "path": "deploy/replicated/requirements/os-specific/centos-requirements" + } + ] + }, + { + "title": "Data Storage", + "routes": [ + { + "title": "Operation Mode", + "path": "deploy/replicated/requirements/data-storage/operational-mode-requirements" + }, + { + "title": "PostgreSQL", + "path": "deploy/replicated/requirements/data-storage/postgres-requirements" + }, + { + "title": "Minio Setup Guide", + "path": "deploy/replicated/requirements/data-storage/minio-setup-guide" + } + ] + }, + { + "title": "Network", + "path": "deploy/replicated/requirements/network" + }, + { + "title": "Docker Engine", + "path": "deploy/replicated/requirements/docker_engine" + } + ] + }, + { + "title": "Installation", + "routes": [ + { + "title": "Pre-Install Checklist", + "path": "deploy/replicated/install/pre-install-checklist" + }, + { + "title": "Operation Modes", + "path": "deploy/replicated/install/operation-modes" + }, + { + "title": "Interactive Install", + "routes": [ + { + "title": "1. Run Installer", + "path": "deploy/replicated/install/interactive/installer" + }, + { + "title": "2. Configure in Browser", + "path": "deploy/replicated/install/interactive/config" + } + ] + }, + { + "title": "Automated Install", + "routes": [ + { + "title": "Automated Installation", + "path": "deploy/replicated/install/automated/automating-the-installer" + }, + { + "title": "Active/Active", + "path": "deploy/replicated/install/automated/active-active" + }, + { + "title": "Initial User Automation", + "path": "deploy/replicated/install/automated/automating-initial-user" + }, + { + "title": "Encryption Password", + "path": "deploy/replicated/install/automated/encryption-password" + } + ] + }, + { + "title": "External Vault", + "path": "deploy/replicated/install/vault" + }, + { + "title": "Uninstall", + "path": "deploy/replicated/install/uninstall" + } + ] + }, + { + "title": "Administration", + "routes": [ + { "title": "Overview", "path": "deploy/replicated/administration" }, + { + "title": "License", + "routes": [ + { + "title": "Overview", + "path": "deploy/replicated/administration/license" + }, + { + "title": "Updating Terraform Enterprise License", + "path": "deploy/replicated/administration/license/update-tfe-license" + }, + { + "title": "Automated License Utilization Reporting", + "path": "deploy/replicated/administration/license/automated-license-utilization-reporting" + } + ] + }, + { + "title": "Infrastructure", + "routes": [ + { + "title": "Overview", + "path": "deploy/replicated/administration/infrastructure" + }, + { + "title": "Automated Recovery", + "path": "deploy/replicated/administration/infrastructure/automated-recovery" + }, + { + "title": "Upgrades", + "routes": [ + { + "title":"Overview", + "path": "deploy/replicated/administration/infrastructure/upgrades" + }, + { + "title": "Prepare to upgrade", + "path": "deploy/replicated/administration/infrastructure/upgrades/prepare" + }, + { + "title":"Upgrade", + "path": "deploy/replicated/administration/infrastructure/upgrades/upgrade" + } + ] + }, + { + "title": "Backups and Restores", + "path": "deploy/replicated/administration/infrastructure/backup-restore" + }, + { + "title": "Admin CLI Commands", + "path": "deploy/replicated/administration/infrastructure/admin-cli" + }, + { + "title": "Alternative Worker to Agent Migration", + "path": "deploy/replicated/administration/infrastructure/worker-to-agent-migration" + }, + { + "title": "Migrating from Mounted Disk Mode to External Services Mode", + "path": "deploy/replicated/administration/infrastructure/mounted-to-external-migration" + }, + { + "title": "Consolidated Services", + "path": "deploy/replicated/administration/infrastructure/consolidated-services" + } + ] + } + ] + }, + { + "title": "Architecture", + "routes": [ + { + "title": "Reference", + "routes": [ + { + "title": "Overview", + "path": "deploy/replicated/architecture/reference-architecture" + }, + { + "title": "AWS Reference Architecture", + "path": "deploy/replicated/architecture/reference-architecture/aws" + }, + { + "title": "Azure Reference Architecture", + "path": "deploy/replicated/architecture/reference-architecture/azure" + }, + { + "title": "GCP Reference Architecture", + "path": "deploy/replicated/architecture/reference-architecture/gcp" + }, + { + "title": "VMware Reference Architecture", + "path": "deploy/replicated/architecture/reference-architecture/vmware" + } + ] + }, + { + "title": "System", + "routes": [ + { + "title": "Overview", + "path": "deploy/replicated/architecture/system-overview" + }, + { + "title": "Reliability & Availability", + "path": "deploy/replicated/architecture/system-overview/reliability-availability" + }, + { + "title": "Capacity & Performance", + "path": "deploy/replicated/architecture/system-overview/capacity" + }, + { + "title": "Security Model", + "path": "deploy/replicated/architecture/system-overview/security-model" + }, + { + "title": "Data Security", + "path": "deploy/replicated/architecture/system-overview/data-security" + } + ] + } + ] + }, + { + "title": "Monitoring", + "routes": [ + { + "title": "Log Forwarding", + "path": "deploy/replicated/monitoring/logging" + }, + { + "title": "Metrics and monitoring", + "path": "deploy/replicated/monitoring/monitoring" + } + ] + } + ] + }, + { + "title": "Create initial admin user", + "path": "deploy/initial-admin-user" + }, + { + "title": "Create a custom worker image", + "path": "deploy/custom-image" + }, + { + "title": "Manage deployment", + "routes": [ + { + "title": "Overview", + "path": "deploy/manage" + }, + { + "title": "Connect to Terraform Enterprise CLI", + "path": "deploy/manage/access-cli" + }, + { + "title": "Backup and restore", + "path": "deploy/manage/backup-restore" + }, + { + "title": "Database failover", + "path": "deploy/manage/failover" + }, + { + "title": "Upgrade", + "path": "deploy/manage/upgrade" + }, + { + "title": "Monitor", + "path": "deploy/manage/monitor" + }, + { "title": "Enable automated license utilization reports", + "path": "deploy/manage/license-report" + }, + { "title": "Enable automated product usage reports", + "path": "deploy/manage/product-report" + } + ] + }, + { + "title": "Reference", + "routes": [ + { + "title": "Configuration", + "path": "deploy/reference/configuration" + }, + { + "title": "CLI", + "path": "deploy/reference/cli" + }, + { + "title": "Startup checks", + "path": "deploy/reference/startup-checks" + }, + { + "title": "Container metrics", + "path": "deploy/reference/metrics" + }, + { + "title": "Application services", + "path": "deploy/reference/services" + }, + { + "title": "Data security", + "path": "deploy/reference/data-security" + }, + { + "title": "Application security", + "path": "deploy/reference/application-security" + }, + { + "title": "License usage data", + "path": "deploy/reference/license-data" + }, + { + "title": "Product usage data", + "path": "deploy/reference/product-data" + } + ] + }, + { + "title": "Troubleshoot", + "routes": [ + { + "title": "Overview", + "path": "deploy/troubleshoot" + }, + { + "title": "Contact support", + "path": "deploy/troubleshoot/contact-support" + }, + { + "title": "Perform diagnostics", + "path": "deploy/troubleshoot/perform-diagnostics" + }, + { + "title": "Error messages", + "path": "deploy/troubleshoot/error-messages" + } + ] + } + ] + }, + { + "title": "Application Administration", + "routes": [ + { "title": "Overview", "path": "application-administration" }, + { + "title": "Access the Admin Interface", + "path": "application-administration/admin-access" + }, + { + "title": "General Settings", + "path": "application-administration/general" + }, + { + "title": "Customize the UI", + "path": "application-administration/customization" + }, + { + "title": "Integration Settings", + "path": "application-administration/integration" + }, + { + "title": "OPA Tool Version Settings", + "path": "application-administration/opa-tool-versions" + }, + { + "title": "Sentinel Tool Version Settings", + "path": "application-administration/sentinel-tool-versions" + }, + { + "title": "GitHub App Integration", + "path": "application-administration/github-app-integration" + }, + { + "title": "Manage Accounts and Resources", + "path": "application-administration/resources" + }, + { + "title": "Share Registry Artifacts", + "path": "application-administration/registry-sharing" + }, + { + "title": "Agents on Terraform Enterprise", + "path": "application-administration/agents-on-tfe" + } + ] + }, + { + "title": "Users, Teams, Organizations", + "routes": [ + { "title": "Users", "path": "users-teams-organizations/users" }, + { + "title": "Teams", + "routes": [ + { + "title": "Overview", + "path": "users-teams-organizations/teams" + }, + { + "title": "Manage teams", + "path": "users-teams-organizations/teams/manage" + }, + { + "title": "Notifications", + "path": "users-teams-organizations/teams/notifications" + } + ] + }, + { + "title": "Organizations", + "routes": [ + {"title": "Overview","path": "users-teams-organizations/organizations"}, + { + "title": "Manage reserved tag keys", + "path": "users-teams-organizations/organizations/manage-reserved-tags" + }, + { "title": "VCS status checks", "path": "users-teams-organizations/organizations/vcs-status-checks" }, + { "title": "Automatically cancel plan-only runs", "path": "users-teams-organizations/organizations/vcs-speculative-plan-management" } + ] + }, + { + "title": "Permissions", + "path": "users-teams-organizations/permissions" + }, + + { + "title": "Two-factor Authentication", + "path": "users-teams-organizations/2fa" + }, + { + "title": "API Tokens", + "path": "users-teams-organizations/api-tokens" + } + ] + }, + { + "title": "SAML SSO", + "routes": [ + { + "title": "Configuration", + "path": "saml/configuration" + }, + { + "title": "Team Membership", + "path": "saml/team-membership" + }, + { + "title": "Attributes", + "path": "saml/attributes" + }, + { + "title": "Login", + "path": "saml/login" + }, + { + "title": "Identity Providers", + "routes": [ + { + "title": "Sample Auth Request", + "path": "saml/idp-configuration" + }, + { + "title": "ADFS", + "path": "saml/idp-configuration/adfs" + }, + { + "title": "Azure Active Directory", + "path": "saml/idp-configuration/aad" + }, + { + "title": "Okta", + "path": "saml/idp-configuration/okta" + }, + { + "title": "OneLogin", + "path": "saml/idp-configuration/onelogin" + } + ] + }, + { + "title": "Troubleshooting", + "path": "saml/troubleshooting" + } + ] + }, + { + "title": "Projects", + "routes": [ + { "title": "Overview", "path": "projects" }, + { + "title": "Managing Projects", + "path": "projects/manage" + }, + { "title": "Best Practices", "path": "projects/best-practices" } + ] + }, + { + "title": "Workspaces", + "routes": [ + { "title": "Overview", "path": "workspaces" }, + { + "title": "Create Workspaces", + "path": "workspaces/create" + }, + { + "title": "Create tags", + "path": "workspaces/tags" + }, + { + "title": "Browse workspaces", + "path": "workspaces/browse" + }, + { + "title": "Terraform Configurations", + "path": "workspaces/configurations" + }, + { + "title": "Dynamic Provider Credentials", + "routes": [ + { + "title": "Overview", + "path": "workspaces/dynamic-provider-credentials" + }, + { + "title": "Workload Identity Tokens", + "path": "workspaces/dynamic-provider-credentials/workload-identity-tokens" + }, + { + "title": "Vault Configuration", + "path": "workspaces/dynamic-provider-credentials/vault-configuration" + }, + { + "title": "AWS Configuration", + "path": "workspaces/dynamic-provider-credentials/aws-configuration" + }, + { + "title": "GCP Configuration", + "path": "workspaces/dynamic-provider-credentials/gcp-configuration" + }, + { + "title": "Azure Configuration", + "path": "workspaces/dynamic-provider-credentials/azure-configuration" + }, + { "title": "Kubernetes Configuration", + "path": "workspaces/dynamic-provider-credentials/kubernetes-configuration" + }, + { + "title": "HCP Configuration", + "path": "workspaces/dynamic-provider-credentials/hcp-configuration" + }, + { + "title": "HCP Vault Secrets", + "routes": [ + { + "title": "Overview", + "path": "workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed" + }, + { + "title": "AWS Configuration", + "path": "workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration" + }, + { + "title": "GCP Configuration", + "path": "workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration" + } + ] + }, + { + "title": "Manually Generating Workload Identity Tokens", + "path": "workspaces/dynamic-provider-credentials/manual-generation" + }, + { + "title": "Specifying Multiple Configurations", + "path": "workspaces/dynamic-provider-credentials/specifying-multiple-configurations" + }, + { + "title": "Vault-Backed Dynamic Credentials", + "routes": [ + { + "title": "Overview", + "path": "workspaces/dynamic-provider-credentials/vault-backed" + }, + { + "title": "AWS Configuration", + "path": "workspaces/dynamic-provider-credentials/vault-backed/aws-configuration" + }, + { + "title": "GCP Configuration", + "path": "workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration" + }, + { + "title": "Azure Configuration", + "path": "workspaces/dynamic-provider-credentials/vault-backed/azure-configuration" + } + ] + } + ] + }, + { + "title": "Variables", + "routes": [ + { "title": "Overview", "path": "workspaces/variables" }, + { + "title": "Managing Variables", + "path": "workspaces/variables/managing-variables" + } + ] + }, + { "title": "Health", "path": "workspaces/health" }, + { + "title": "Settings", + "routes": [ + { "title": "Overview", "path": "workspaces/settings" }, + { "title": "VCS Connections", "path": "workspaces/settings/vcs" }, + { "title": "Access", "path": "workspaces/settings/access" }, + { + "title": "Notifications", + "path": "workspaces/settings/notifications" + }, + { + "title": "SSH Keys for Modules", + "path": "workspaces/settings/ssh-keys" + }, + { + "title": "Run Triggers", + "path": "workspaces/settings/run-triggers" + }, + { + "title": "Run Tasks", + "path": "workspaces/settings/run-tasks" + }, + { + "title": "Destruction and Deletion", + "path": "workspaces/settings/deletion" + } + ] + }, + { "title": "Terraform State", "path": "workspaces/state" }, + { + "title": "JSON Filtering", + "path": "workspaces/json-filtering" + }, + { "title": "Best Practices", "path": "workspaces/best-practices"} + ] + }, + { + "title": "Terraform Runs", + "routes": [ + { "title": "Remote Operations", "path": "run/remote-operations" }, + { "title": "Viewing and Managing Runs", "path": "run/manage" }, + { "title": "Run States and Stages", "path": "run/states" }, + { "title": "Run Modes and Options", "path": "run/modes-and-options" }, + { "title": "UI/VCS-driven Runs", "path": "run/ui" }, + { "title": "API-driven Runs", "path": "run/api" }, + { "title": "CLI-driven Runs", "path": "run/cli" }, + { + "title": "The Run Environment", + "path": "run/run-environment" + }, + { + "title": "Installing Software", + "path": "run/install-software" + } + ] + }, + + { + "title": "Connect to VCS", + "routes": [ + { "title": "Overview", "path": "vcs" }, + { "title": "GitHub.com (OAuth)", "path": "vcs/github" }, + { + "title": "GitHub Enterprise", + "path": "vcs/github-enterprise" + }, + { "title": "GitLab.com", "path": "vcs/gitlab-com" }, + { "title": "GitLab EE and CE", "path": "vcs/gitlab-eece" }, + { "title": "Bitbucket Cloud", "path": "vcs/bitbucket-cloud" }, + { + "title": "Bitbucket Data Center", + "path": "vcs/bitbucket-data-center" + }, + { + "title": "Azure DevOps Services", + "path": "vcs/azure-devops-services" + }, + { + "title": "Azure DevOps Server", + "path": "vcs/azure-devops-server" + }, + { "title": "Troubleshooting", "path": "vcs/troubleshooting" } + ] + }, + + { + "title": "Private Registry", + "routes": [ + { "title": "Overview", "path": "registry" }, + { + "title": "Adding Public Providers and Modules", + "path": "registry/add" + }, + { + "title": "Publishing Private Providers", + "path": "registry/publish-providers" + }, + { + "title": "Public Providers in an Airgapped Installation", + "path": "registry/airgapped-providers" + }, + { + "title": "Publishing Private Modules", + "path": "registry/publish-modules" + }, + { "title": "Deprecate Module Versions", "path": "registry/manage-module-versions" }, + { + "title": "Test-Integrated Modules", + "path": "registry/test" + }, + { "title": "Using Providers and Modules", "path": "registry/using" }, + { + "title": "Configuration Designer", + "path": "registry/design" + } + ] + }, + { + "title": "No-Code Provisioning", + "routes": [ + { + "title": "Designing No-Code Ready Modules", + "path": "no-code-provisioning/module-design" + }, + { + "title": "Provisioning No-Code Infrastructure", + "path": "no-code-provisioning/provisioning" + } + ] + }, + { + "title": "Migrating to Terraform Enterprise", + "routes": [ + { + "title": "Manually migrate", + "path": "migrate" + }, + { + "title": "Use the tf-migrate CLI", + "routes": [ + { + "title": "Overview", + "path": "migrate/tf-migrate" + }, + { + "title": "tf-migrate commands reference", + "routes": [ + { + "title": "Configuration file reference", + "path": "migrate/tf-migrate/reference/configuration" + }, + { + "title": "prepare command", + "path": "migrate/tf-migrate/reference/prepare" + }, + { + "title": "execute command", + "path": "migrate/tf-migrate/reference/execute" + } + ] + } + ] + } + ] + }, + { + "title": "Policy enforcement", + "routes": [ + { + "title": "Overview", + "path": "policy-enforcement" + }, + { + "title": "Define policies", + "routes": [ + { + "title": "Overview", + "path": "policy-enforcement/define-policies" + }, + { + "title": "Custom Sentinel policies", + "path": "policy-enforcement/define-policies/custom-sentinel" + }, + { + "title": "OPA policies", + "path": "policy-enforcement/define-policies/opa" + } + ] + }, + { + "title": "Create and manage policy sets", + "routes": [ + { + "title": "Overview", + "path": "policy-enforcement/manage-policy-sets" + }, + { + "title": "Create Sentinel policy sets in VCS", + "path": "policy-enforcement/manage-policy-sets/sentinel-vcs" + }, + { + "title": "Connect to OPA policies in VCS", + "path": "policy-enforcement/manage-policy-sets/opa-vcs" + } + ] + }, + { + "title": "Run pre-written Sentinel policies", + "path": "policy-enforcement/prewritten-sentinel" + }, + { + "title": "Test Sentinel policies", + "path": "policy-enforcement/test-sentinel" + }, + { + "title": "View policy results", + "routes": [ + { + "title": "Overview", + "path": "policy-enforcement/view-results" + }, + { + "title": "View Sentinel JSON results", + "path": "policy-enforcement/view-results/json" + } + ] + }, + { + "title": "Pre-written policy library", + "path": "policy-enforcement/prewritten-library" + }, + { + "title": "Sentinel import reference", + "routes": [ + { + "title": "Overview", + "path": "policy-enforcement/import-reference" + }, + { + "title": "tfconfig", + "path": "policy-enforcement/import-reference/tfconfig" + }, + { + "title": "tfconfig/v2", + "path": "policy-enforcement/import-reference/tfconfig-v2" + }, + { + "title": "tfplan", + "path": "policy-enforcement/import-reference/tfplan" + }, + { + "title": "tfplan/v2", + "path": "policy-enforcement/import-reference/tfplan-v2" + }, + { + "title": "tfstate", + "path": "policy-enforcement/import-reference/tfstate" + }, + { + "title": "tfstate/v2", + "path": "policy-enforcement/import-reference/tfstate-v2" + }, + { + "title": "tfrun", + "path": "policy-enforcement/import-reference/tfrun" + } + ] + } + ] + }, + { + "title": "Cost Estimation", + "routes": [ + { "title": "Overview", "path": "cost-estimation" }, + { "title": "AWS", "path": "cost-estimation/aws" }, + { "title": "GCP", "path": "cost-estimation/gcp" }, + { "title": "Azure", "path": "cost-estimation/azure" } + ] + }, + + { + "title": "Integrations", + "routes": [ + { + "title": "Overview", + "path": "integrations" + }, + { + "title": "Kubernetes Operator", + "routes": [ + { + "title": "Overview", + "path": "integrations/kubernetes" + }, + { + "title": "Setup", + "path": "integrations/kubernetes/setup" + }, + { + "title": "API Reference", + "path": "integrations/kubernetes/api-reference" + }, + { + "title": "Annotations and Labels", + "path": "integrations/kubernetes/annotations-and-labels" + }, + { + "title": "Migration Guide", + "path": "integrations/kubernetes/ops-v2-migration" + } + ] + }, + { + "title": "ServiceNow Integrations", + "routes": [ + { + "title": "Service Catalog for Terraform", + "routes": [ + { + "title": "Overview", + "path": "integrations/service-now/service-catalog-terraform" + }, + { + "title": "Service Catalog", + "path": "integrations/service-now/service-catalog-terraform/service-catalog-config" + }, + { + "title": "Admin Guide", + "path": "integrations/service-now/service-catalog-terraform/admin-guide" + }, + { + "title": "Developer Reference", + "path": "integrations/service-now/service-catalog-terraform/developer-reference" + }, + { + "title": "Example Customizations", + "path": "integrations/service-now/service-catalog-terraform/example-customizations" + }, + { + "title": "Troubleshoot", + "path": "integrations/service-now/service-catalog-terraform/troubleshoot" + } + ] + }, + { + "title": "Service Graph Connector for Terraform", + "routes": [ + { + "title": "Overview", + "path": "integrations/service-now/service-graph" + }, + { + "title": "Setup", + "path": "integrations/service-now/service-graph/service-graph-setup" + }, + { + "title": "Resource Coverage", + "routes": [ + { + "title": "Overview", + "path": "integrations/service-now/service-graph/resource-coverage" + }, + { + "title": "AWS", + "path": "integrations/service-now/service-graph/resource-coverage/aws" + }, + { + "title": "Azure", + "path": "integrations/service-now/service-graph/resource-coverage/azure" + }, + { + "title": "GCP", + "path": "integrations/service-now/service-graph/resource-coverage/gcp" + }, + { + "title": "vSphere", + "path": "integrations/service-now/service-graph/resource-coverage/vsphere" + } + ] + }, + { + "title": "Customizations", + "path": "integrations/service-now/service-graph/customizations" + } + ] + } + ] + }, + { + "title": "Run Tasks Integration", + "path": "integrations/run-tasks" + }, + { + "title": "AWS Service Catalog Integration", + "path": "integrations/aws-service-catalog" + } + ] + }, + { + "title": "Releases", + "routes": [ + { + "title": "Overview", + "path": "releases" + }, + { + "title": "2025", + "routes": [ + { "title": "Overview", "path": "releases/2025" }, + { "title": "v202504-1", "path": "releases/2025/v202504-1" }, + { "title": "v202503-1", "path": "releases/2025/v202503-1" }, + { "title": "v202502-2", "path": "releases/2025/v202502-2" }, + { "title": "v202502-1", "path": "releases/2025/v202502-1" }, + { "title": "v202501-1", "path": "releases/2025/v202501-1" } + ] + }, + { + "title": "2024", + "routes": [ + { "title": "Overview", "path": "releases/2024" }, + { "title": "v202411-2", "path": "releases/2024/v202411-2" }, + { "title": "v202411-1", "path": "releases/2024/v202411-1" }, + { "title": "v202410-1", "path": "releases/2024/v202410-1" }, + { "title": "v202409-3", "path": "releases/2024/v202409-3" }, + { "title": "v202409-2", "path": "releases/2024/v202409-2" }, + { "title": "v202409-1", "path": "releases/2024/v202409-1" }, + { "title": "v202408-1", "path": "releases/2024/v202408-1" }, + { "title": "v202407-1", "path": "releases/2024/v202407-1" }, + { "title": "v202406-1", "path": "releases/2024/v202406-1" }, + { "title": "v202405-1", "path": "releases/2024/v202405-1" }, + { "title": "v202404-2", "path": "releases/2024/v202404-2" }, + { "title": "v202404-1", "path": "releases/2024/v202404-1" }, + { "title": "v202402-2", "path": "releases/2024/v202402-2" }, + { "title": "v202402-1", "path": "releases/2024/v202402-1" }, + { "title": "v202401-2", "path": "releases/2024/v202401-2" }, + { "title": "v202401-1", "path": "releases/2024/v202401-1" } + ] + }, + { + "title": "2023", + "routes": [ + { "title": "Overview", "path": "releases/2023" }, + { "title": "v202312-1", "path": "releases/2023/v202312-1" }, + { "title": "v202311-1", "path": "releases/2023/v202311-1" }, + { "title": "v202310-1", "path": "releases/2023/v202310-1" }, + { "title": "v202309-1", "path": "releases/2023/v202309-1" }, + { "title": "v202308-1", "path": "releases/2023/v202308-1" }, + { "title": "v202307-1", "path": "releases/2023/v202307-1" }, + { "title": "v202306-1", "path": "releases/2023/v202306-1" }, + { "title": "v202305-2", "path": "releases/2023/v202305-2" }, + { "title": "v202305-1", "path": "releases/2023/v202305-1" }, + { "title": "v202304-1", "path": "releases/2023/v202304-1" }, + { "title": "v202303-1", "path": "releases/2023/v202303-1" }, + { "title": "v202302-1", "path": "releases/2023/v202302-1" }, + { "title": "v202301-2", "path": "releases/2023/v202301-2" }, + { "title": "v202301-1", "path": "releases/2023/v202301-1" } + ] + }, + { + "title": "2022", + "routes": [ + { "title": "Overview", "path": "releases/2022" }, + { "title": "v202212-2", "path": "releases/2022/v202212-2" }, + { "title": "v202212-1", "path": "releases/2022/v202212-1" }, + { "title": "v202211-1", "path": "releases/2022/v202211-1" }, + { "title": "v202210-1", "path": "releases/2022/v202210-1" }, + { "title": "v202209-2", "path": "releases/2022/v202209-2" }, + { "title": "v202209-1", "path": "releases/2022/v202209-1" }, + { "title": "v202208-3", "path": "releases/2022/v202208-3" }, + { "title": "v202208-2", "path": "releases/2022/v202208-2" }, + { "title": "v202208-1", "path": "releases/2022/v202208-1" }, + { "title": "v202207-2", "path": "releases/2022/v202207-2" }, + { "title": "v202207-1", "path": "releases/2022/v202207-1" }, + { "title": "v202206-1", "path": "releases/2022/v202206-1" }, + { "title": "v202205-1", "path": "releases/2022/v202205-1" }, + { "title": "v202204-2", "path": "releases/2022/v202204-2" }, + { "title": "v202204-1", "path": "releases/2022/v202204-1" }, + { "title": "v202203-1", "path": "releases/2022/v202203-1" }, + { "title": "v202202-1", "path": "releases/2022/v202202-1" }, + { "title": "v202201-2", "path": "releases/2022/v202201-2" }, + { "title": "v202201-1", "path": "releases/2022/v202201-1" } + ] + }, + { + "title": "2021", + "routes": [ + { "title": "Overview", "path": "releases/2021" }, + { "title": "v202112-2", "path": "releases/2021/v202112-2" }, + { "title": "v202112-1", "path": "releases/2021/v202112-1" }, + { "title": "v202111-1", "path": "releases/2021/v202111-1" }, + { "title": "v202110-1", "path": "releases/2021/v202110-1" }, + { "title": "v202109-2", "path": "releases/2021/v202109-2" }, + { "title": "v202109-1", "path": "releases/2021/v202109-1" }, + { "title": "v202108-1", "path": "releases/2021/v202108-1" }, + { "title": "v202107-1", "path": "releases/2021/v202107-1" }, + { "title": "v202106-1", "path": "releases/2021/v202106-1" }, + { "title": "v202105-1", "path": "releases/2021/v202105-1" }, + { "title": "v202104-1", "path": "releases/2021/v202104-1" }, + { "title": "v202103-3", "path": "releases/2021/v202103-3" }, + { "title": "v202103-2", "path": "releases/2021/v202103-2" }, + { "title": "v202103-1", "path": "releases/2021/v202103-1" }, + { "title": "v202102-2", "path": "releases/2021/v202102-2" }, + { "title": "v202102-1", "path": "releases/2021/v202102-1" }, + { "title": "v202101-1", "path": "releases/2021/v202101-1" } + ] + }, + { + "title": "2020", + "routes": [{ "title": "Overview", "path": "releases/2020" }] + }, + { + "title": "2019", + "routes": [{ "title": "Overview", "path": "releases/2019" }] + }, + { + "title": "2018", + "routes": [{ "title": "Overview", "path": "releases/2018" }] + } + ] + }, + { "divider": true }, + { "title": "HCP Terraform Agents", "href": "/cloud-docs/agents" } +] diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/.gitkeep b/content/terraform-enterprise/v000011-1/v202504-1/docs/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/_template.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/_template.mdx new file mode 100644 index 0000000000..94c74253f0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/_template.mdx @@ -0,0 +1,222 @@ +--- +page_title: /example-endpoint API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/endpoint-name` to {A meaningful + description of this endpoint}. Aim for 130-160 characters total. +source: terraform-docs-common +--- + +Follow this template to format each API method. There are usually multiple sections like this on a given API endpoint page. + + + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: http://jsonapi.org/format/#error-objects + +# Example name API reference + +A explanatory sentence about what this thing in HCP Terraform does. + +## Create a Something + +Add at least one sentence of description about what this endpoint does. + + + +`POST /organizations/:organization_name/somethings` + + + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to create the something in. The organization must already exist in the system, and the user must have permissions to create new somethings. | + + + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + + + +| Status | Response | Reason | +| ------- | -------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "somethings"`) | Successfully created a team | +| [400][] | [JSON API error object][] | Invalid `include` parameter | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during team creation | + + + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + + + +| Parameter | Description | +| ----------------------- | ------------------------------------------------------------- | +| `filter[workspace][id]` | **Required.** The workspace ID where this action will happen. | + + + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + + + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"somethings"`. | +| `data[].type` | string | | ... | +| `data.attributes.category` | string | | Whether this is a blue or red something. Valid values are `"blue"` or `"red"`. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the something is written once and not visible thereafter. | +| `filter.workspace.name` | string | | The name of the workspace that owns the something. | +| `filter.organization.name` | string | | The name of the organization that owns the workspace. | + + + +### Available Related Resources + + + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------------ | --------------------------------------------- | +| `organization` | The full organization record. | +| `current_run` | Additional information about the current run. | +| `current_run.plan` | The plan used in the current run. | + +### Sample Payload + +```json +{ + "data": { + "type":"somethings", + "attributes": { + "category":"red", + "sensitive":true + } + }, + "filter": { + "organization": { + "name":"my-organization" + }, + "workspace": { + "name":"my-workspace" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/somethings +``` + + + +### Sample Response + +```json +{ + "data": { + "id":"som-EavQ1LztoRTQHSNT", + "type":"somethings", + "attributes": { + "sensitive":true, + "category":"red", + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/somethings/som-EavQ1LztoRTQHSNT" + } + } +} +``` + + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/account.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/account.mdx new file mode 100644 index 0000000000..570770ef0d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/account.mdx @@ -0,0 +1,278 @@ +--- +page_title: /account API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/account` endpoint to manage the current + user. Learn how to read and update your account's details and change your + password. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Account API reference + +Account represents the current user interacting with Terraform. It returns the same type of object as the [Users](/terraform/enterprise/api-docs/users) API, but also includes an email address, which is hidden when viewing info about other users. + +For internal reasons, HCP Terraform associates team and organization tokens with a synthetic user account called _service user_. HCP Terraform returns the associated service user for account requests authenticated by a team or organization token. Use the `authenticated-resource` relationship to access the underlying team or organization associated with a token. For user tokens, you can use the user, itself. + +## Get your account details + +`GET /account/details` + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | The request was successful | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/account/details +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "tfc", + "avatar-url": "https://www.gravatar.com/avatar/9babb00091b97b9ce9538c45807fd35f?s=100&d=mm", + "v2-only": false, + "is-site-admin": true, + "is-sso-login": false, + "email": "admin@hashicorp.com", + "unconfirmed-email": null, + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN/authentication-tokens" + } + }, + "authenticated-resource": { + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } + }, + "links": { + "self": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } +} +``` + +## Update your account info + +Your username and email address can be updated with this endpoint. + +`PATCH /account/update` + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Your info was successfully updated | +| [401][] | [JSON API error object][] | Unauthorized | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | --------------------------------------------------------------- | +| `data.type` | string | | Must be `"users"` | +| `data.attributes.username` | string | | New username | +| `data.attributes.email` | string | | New email address (must be confirmed afterwards to take effect) | + +### Sample Payload + +```json +{ + "data": { + "type": "users", + "attributes": { + "email": "admin@example.com", + "username": "admin" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/account/update +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "hcp_username_password", + "avatar-url": "https://www.gravatar.com/avatar/9babb00091b97b9ce9538c45807fd35f?s=100&d=mm", + "v2-only": false, + "is-site-admin": true, + "is-sso-login": false, + "email": "admin@hashicorp.com", + "unconfirmed-email": null, + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } +} +``` + +## Change your password + +`PATCH /account/password` + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Your password was successfully changed | +| [401][] | [JSON API error object][] | Unauthorized | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------------------------------------- | ------ | ------- | ------------------------------------------------------- | +| `data.type` | string | | Must be `"users"` | +| `data.attributes.current_password` | string | | Current password | +| `data.attributes.password` | string | | New password (must be at least 10 characters in length) | +| `data.attributes.password_confirmation` | string | | New password (confirmation) | + +### Sample Payload + +```json +{ + "data": { + "type": "users", + "attributes": { + "current_password": "current password e.g. 2:C)e'G4{D\n06:[d1~y", + "password": "new password e.g. 34rk492+jgLL0@xhfyisj", + "password_confirmation": "new password e.g. 34rk492+jLL0@xhfyisj" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/account/password +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "hcp_github", + "avatar-url": "https://www.gravatar.com/avatar/9babb00091b97b9ce9538c45807fd35f?s=100&d=mm", + "v2-only": false, + "is-site-admin": true, + "is-sso-login": false, + "email": "admin@hashicorp.com", + "unconfirmed-email": null, + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/index.mdx new file mode 100644 index 0000000000..e2138cb2f8 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/index.mdx @@ -0,0 +1,17 @@ +--- +page_title: /admin API reference for Terraform Enterprise +description: >- + Use the `/admin` set of endpoints to configure and support your Terraform Enterprise installation. Learn about operations available in the HTTP API. +--- + +# Terraform Enterprise Admin API Documentation + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + +Terraform Enterprise provides an API to allow administrators to configure and support their installation. + +## Authentication + +With the exception of the [user impersonation endpoints](/terraform/enterprise/api-docs/admin/users#impersonate-another-user), all requests must be authenticated with a bearer token belonging to a site administrator. Use the HTTP Header `Authorization` with the value `Bearer `. This token can be generated or revoked on the [tokens tab of the user settings page](/terraform/enterprise/users-teams-organizations/users#api-tokens). In the context of the Admin API, your token has management access to all resources in the system. + +For more information on authentication behavior, refer to [the API overview section](/terraform/enterprise/api-docs#authentication). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/initial-admin-user.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/initial-admin-user.mdx new file mode 100644 index 0000000000..e64a4f6e84 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/initial-admin-user.mdx @@ -0,0 +1,69 @@ +--- +page_title: /initial-admin-user/ API reference for Terraform Enterprise +description: Learn how to call the initial-admin-user API endpoint to create the initial admin user. +--- + +# `initial-admin-user` API endpoint + +This topic provides reference information about the `initial-admin-user` API endpoint. + +## Introduction + +Send a `POST` request to the `/initial-admin-user` API endpoint to create the initial admin user after deploying Terraform Enterprise. Refer to [Create the initial admin user](/terraform/enterprise/deploy/initial-admin-user) for additional information. + +## Query parameters + +The following table describes the URL query parameters you can include in the request. If your client does not automatically encode URLs, use HTML URL-encoding characters to ensure that requests are successful. + +| Parameter | Description | +| --------- | --------------------------------------------------------- | +| `token` | **Required.** The IACT token retrieved via API or command | + +## Request body + +This `POST` endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type |Description | +| ---------- | ------ |------------------------------------ | +| `username` | string |The username to assign the new user. | +| `email` | string |The email address of the new user. | +| `password` | string |The password of the new user. | + +## Response body + +The `POST` endpoint returns a JSON object with the following properties. + +| Key path | Type | Description | +| -------- | ------ | -------------------------------------------------------------------------- | +| `status` | string | Either `"created"` or `"error"`. | +| `token` | string | If status is `"created"`, this contains a Terraform Enterprise user token for the new user. | +| `error` | string | If status is `"error"`, this contains the reason for the error. | + +## Sample payload + +```json +{ + "username": "manage", + "email": "it@mycompany.com", + "password": "thisisabadpassword" +} +``` + +## Sample request + +```shell +curl \ + --header "Content-Type: application/json" \ + --request POST \ + --data @payload.json \ + https://${TFE_HOSTNAME}/admin/initial-admin-user?token=${IACT_TOKEN} +``` + +## Sample response + +```json +{ + "status": "created", + "token": "aabbccdd.v1.atlas.ddeeffgghhiijjkkllmmnnooppqqrrssttuuvvxxyyzz" +} +``` \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/module-sharing.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/module-sharing.mdx new file mode 100644 index 0000000000..1edd604bc7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/module-sharing.mdx @@ -0,0 +1,121 @@ +--- +page_title: /module-consumers API reference for Terraform Enterprise +description: >- + Use the `/module-consumers` endpoint to manage sharing permissions for modules in your registry. Learn how to update an organization's module consumers using the API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin Module Consumers API + +Admins and operators who install and maintain their organization's Terraform Enterprise instance are able to use the `module-consumers` endpoint. + +~> **This endpoint is deprecated**: We will remove this endpoint in a future release. Use the [Registry Sharing API](/terraform/enterprise/api-docs/admin/registry-sharing) instead. Continue using the [Admin Organizations API](/terraform/enterprise/api-docs/admin/organizations#update-an-organization) to configure global module sharing. + +There are two ways to configure module sharing using the Admin API: + +- This endpoint, which allows an organization to share modules with a specific list of other organizations. +- The [update an organization endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization), whose `data.attributes.global-module-sharing` property allows an organization to share modules with every organization in the instance. + + +## Update an Organization's Module Consumers + +-> This API endpoint is available in Terraform Enterprise as of version 202012-1. + +`PATCH /admin/organizations/:name/module-consumers` + +This endpoint sets the list of organizations that can use modules from the sharing organization's private registry. Sharing with specific organizations will automatically turn off global module sharing, which is configured with the [update an organization endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization) (via the `data.attributes.global-module-sharing` property). + +| Parameter | Description | +| --------- | ----------------------------------------------------------- | +| `:name` | The name of the organization whose registry is being shared | + +| Status | Response | Reason | +| ------- | ----------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "module-partnerships"`) | The list of module consumers was successfully updated | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------------------------------------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"module-partnerships"` | +| `data.attributes.module-consuming-organization-ids` | array\[string] | | A list of external ids for organizations that will be able to access modules in the producing organization's registry. These should have an `org-` prefix. | + +### Sample Payload + +```json +{ + "data": { + "type": "module-partnerships", + "attributes": { + "module-consuming-organization-ids": [ + "org-939hp5K7kecppVmd" + ] + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://tfe.example.com/api/v2/admin/organizations/my-organization/module-consumers +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "mp-tQATArr4gyYDBvkF", + "type": "module-partnerships", + "attributes": { + "consuming-organization-id": "org-939hp5K7kecppVmd", + "consuming-organization-name": "other-organization", + "producing-organization-id": "org-etdex8r9VLnyHFct", + "producing-organization-name": "my-organization" + } + } + ] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/opa-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/opa-versions.mdx new file mode 100644 index 0000000000..63effadd7c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/opa-versions.mdx @@ -0,0 +1,358 @@ +--- +page_title: /admin/opa-versions API reference for Terraform Enterprise +description: >- + Use the `/admin/opa-versions` endpoint to manage available Open Policy Agent (OPA) versions. Learn how to list, show, create, update, and delete OPA versions using the HTTP API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin OPA Versions API + +The `/opa-versions` endpoint lets site administrators manage which versions of OPA you can use to enforce policies. + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + +## List all OPA versions + +`GET /api/v2/admin/opa-versions` + +This endpoint lists all known versions of OPA. + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------- | +| [200][] | [JSON API document][] (`type: "opa-versions"`) | Successfully lists OPA versions. | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[version]` | **Optional.** A query string. This will find an exact OPA version matching the version queried. This option takes precedence over search queries. | +| `search[version]` | **Optional.** A search query string. This will search for OPA versions matching the version number queried. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 OPA versions per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/admin/opa-versions" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "opa-versions", + "attributes": { + "version": "0.55.0", + "url": "https://github.com/open-policy-agent/opa/releases/download/v0.55.0/opa_linux_arm64_static", + "sha": "d19603df4ab619e98cc515084f62b839464ee5bff61383d1df7724db8a7027a9", + "deprecated": false, + "deprecated-reason": null, + "official": true, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + }, + { + "id": "tool-qcbYn12vuRKPgPpy", + "type": "opa-versions", + "attributes": { + "version": "0.54.0", + "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static", + "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8", + "deprecated": false, + "deprecated-reason": null, + "official": true, + "enabled": true, + "beta": false, + "usage": 2, + "created-at": "2023-08-23T22:34:24.561Z" + } + } + ], + "links": { + "self": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20", + "last": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=4&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": 2, + "total-pages": 4, + "total-count": 70 + } + } +} +``` + +## Create an OPA version + +`POST /api/v2/admin/opa-versions` + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | ---------------------------------------------- | +| [201][] | [JSON API document][] (`type: "opa-versions"`) | The OPA version was successfully created. | +| [404][] | [JSON API error object][] | Client is not an administrator. | +| [422][] | [JSON API error object][] | Validation errors. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"opa-versions"`. | +| `data.attributes.version` | string | | A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`). | +| `data.attributes.url` | string | | The URL where you can download the 64-bit Linux binary of this version. | +| `data.attributes.sha` | string | | The SHA-256 checksum of the OPA binary. | +| `data.attributes.deprecated` | bool | `false` | Whether or not this version of OPA is deprecated. | +| `data.attributes.deprecated-reason` | string | `null` | Additional context about why a version of OPA is deprecated. Field is null unless deprecated is `true`. | +| `data.attributes.official` | bool | `false` | Whether or not this is an official release of OPA. | +| `data.attributes.enabled` | bool | `true` | Whether or not this version of OPA is enabled for use in HCP Terraform. | +| `data.attributes.beta` | bool | `false` | Whether or not this version of OPA is a beta pre-release. | + +### Sample Payload + +```json +{ + "data": { + "type": "opa-versions", + "attributes": { + "version": "0.11.8", + "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static", + "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8", + "official": true, + "enabled": true, + "beta": false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/opa-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "opa-versions", + "attributes": { + "version": "0.54.0", + "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static", + "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8", + "official": true, + "deprecated": false, + "deprecated-reason": null, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + } +} +``` + +## Show an OPA version + +`GET /api/v2/admin/opa-versions/:id` + +| Parameter | Description | +| --------- | --------------------------------------- | +| `:id` | The ID of the OPA version to show. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "opa-versions"`) | The request was successful, returns the OPA version with the matching ID. | +| [404][] | [JSON API error object][] | The request could not find a matching OPA version with the specified ID, or the client is not an administrator. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/admin/opa-versions/tool-L4oe7rNwn7J4E5Yr +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "opa-versions", + "attributes": { + "version": "0.54.0", + "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static", + "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8", + "official": true, + "deprecated": false, + "deprecated-reason": null, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + } +} +``` + +## Update an OPA version + +`PATCH /api/v2/admin/opa-versions/:id` + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the OPA version to update. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "opa-versions"`) | The OPA version was successfully updated. | +| [404][] | [JSON API error object][] | The request could not find a matching OPA version with the specified ID, or the client is not an administrator. | +| [422][] | [JSON API error object][] | Validation errors. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ---------------- | ----------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"opa-versions"`. | +| `data.attributes.version` | string | (previous value) | A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`). | +| `data.attributes.url` | string | (previous value) | The URL where you can download the 64-bit Linux binary of this version. | +| `data.attributes.sha` | string | (previous value) | The SHA-256 checksum of the OPA binary. | +| `data.attributes.official` | bool | (previous value) | Whether or not this is an official release of OPA. | +| `data.attributes.deprecated` | bool | (previous value) | Whether or not this version of OPA is deprecated. | +| `data.attributes.deprecated-reason` | string | (previous value) | Additional context about why a version of OPA is deprecated. | +| `data.attributes.enabled` | bool | (previous value) | Whether or not this version of OPA is enabled for use in HCP Terraform. | +| `data.attributes.beta` | bool | (previous value) | Whether or not this version of OPA is a beta pre-release. | + +### Sample Payload + +```json +{ + "data": { + "type": "opa-versions", + "attributes": { + "deprecated": true, + "deprecated-reason": "A bug was discovered in this version of OPA. Please upgrade as soon as possible" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/opa-versions/tool-L4oe7rNwn7J4E5Yr +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "opa-versions", + "attributes": { + "version": "0.54.0", + "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static", + "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8", + "official": true, + "deprecated": true, + "deprecated-reason": "A bug was discovered in this version of OPA. Please upgrade as soon as possible", + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + } +} +``` + +## Delete an OPA version + +`DELETE /api/v2/admin/opa-versions/:id` + +This endpoint removes an OPA version from HCP Terraform. You cannot remove officially labeled OPA versions or versions used by a workspace or policy set. + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the OPA version to delete. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| [204][] | Empty response | The OPA version was successfully deleted. | +| [404][] | [JSON API error object][] | The request could not find a matching OPA version with the specified ID, or the client is not an administrator. | +| [422][] | [JSON API error object][] | The request could not remove the OPA version because it is an official version or a workspace or policy set uses it. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/admin/opa-versions/tool-L4oe7rNwn7J4E5Yr +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/organizations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/organizations.mdx new file mode 100644 index 0000000000..2943057cc5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/organizations.mdx @@ -0,0 +1,624 @@ +--- +page_title: /admin/organizations API reference for Terraform Enterprise +description: >- + Use the `/admin/organizations` endpoint to manage organizations. Learn how to list, show, update, and delete organizations, list module and provider consumers, and update module consumers. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin Organizations API + +The `admin/organizations` API endpoint contains endpoints to help site administrators manage organizations. + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + + + +## List all Organizations + +`GET /api/v2/admin/organizations` + +This endpoint lists all organizations in the Terraform Enterprise installation. + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | --------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | Successfully listed organizations | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Organizations are searchable by name and notification email. This query takes precedence over the attribute specific searches `q[email]` or `q[name]`. | +| `q[email]` | **Optional.** A search query string. This query searches organizations by notification email. If used with `q[name]`, it returns organizations that match both queries. | +| `q[name]` | **Optional.** A search query string. This query searches organizations by name. If used with `q[email]`, it returns organizations that match both queries. | +| `filter[module_producer]` | **Optional.** Allows filtering organizations based on their module sharing configuration. Accepts a boolean true/false value. A `true` value returns organizations that are configured to share their modules, and a `false` value returns organizations that are not configured to share their modules. | +| `filter[provider_producer]` | **Optional.** Allows filtering organizations based on their provider sharing configuration. Accepts a boolean true/false value. A `true` value returns organizations that are configured to share their providers, and a `false` value returns organizations that are not configured to share their providers. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 organizations per page. | + +### Available Related Resources + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | --------------------------------------- | +| `owners` | A list of owners for each organization. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://tfe.example.com/api/v2/admin/organizations" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "my-organization", + "type": "organizations", + "attributes": { + "access-beta-tools": false, + "external-id": "org-XBiRp755dav5p3P2", + "is-disabled": false, + "name": "my-organization", + "apply-timeout": null, + "plan-timeout": null, + "terraform-worker-sudo-enabled": false, + "notification-email": "my-organization@example.com", + "global-module-sharing": false, + "global-provider-sharing": false, + "sso-enabled": false, + "workspace-limit": null + }, + "relationships": { + "owners": { + "data": [ + { + "id": "user-hxTQDETqnJsi5VYP", + "type": "users" + } + ] + }, + "subscription": { + "data": null + }, + "feature-set": { + "data": null + }, + "module-consumers": { + "links": { + "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers" + } + } + }, + "links": { + "self": "/api/v2/admin/organizations/my-organization" + } + } + ], + "links": { + "self": "https://tfe.example.com/api/v2/admin/organizations?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/admin/organizations?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://tfe.example.com/api/v2/admin/organizations?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20" + }, + "meta": { + "status-counts": { + "total": 1, + "active": 1, + "disabled": 0 + }, + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show an Organization + +`GET /api/v2/admin/organizations/:name` + +| Parameter | Description | +| --------- | ------------------------------------ | +| `:name` | The name of the organization to show | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found, or client is not an administrator | + +### Available Related Resources + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | -------------------------------------- | +| `owners` | A list of owners for the organization. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://tfe.example.com/api/v2/admin/organizations/my-organization +``` + +### Sample Response + +```json +{ + "data": { + "id": "my-organization", + "type": "organizations", + "attributes": { + "access-beta-tools": false, + "external-id": "org-XBiRp755dav5p3P2", + "is-disabled": false, + "name": "my-organization", + "apply-timeout": null, + "plan-timeout": null, + "terraform-worker-sudo-enabled": false, + "notification-email": "my-organization@example.com", + "global-module-sharing": false, + "global-provider-sharing": false, + "sso-enabled": false, + "workspace-limit": null + }, + "relationships": { + "owners": { + "data": [ + { + "id": "user-hxTQDETqnJsi5VYP", + "type": "users" + } + ] + }, + "subscription": { + "data": null + }, + "feature-set": { + "data": null + }, + "module-consumers": { + "links": { + "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers" + } + } + }, + "links": { + "self": "/api/v2/admin/organizations/my-organization" + } + } +} +``` + +## Update an Organization + +`PATCH /admin/organizations/:name` + +| Parameter | Description | +| --------- | -------------------------------------- | +| `:name` | The name of the organization to update | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The organization was successfully updated | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. Note that the Admin Organizations API may offer a different set of attributes than the [Organizations API](/terraform/enterprise/api-docs/organizations#request-body-1). + +| Key path | Type | Default | Description | +| ------------------------------------------------------ | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"organizations"` | +| `data.attributes.access-beta-tools` | boolean | false | Whether or not workspaces in the organization can be configured to use beta Terraform versions. | +| `data.attributes.global-module-sharing` | boolean | false | If true, modules in the organization's private module repository will be available to all other organizations in this Terraform Enterprise instance. Enabling this will disable any previously configured [module consumers](#list-module-consumers-for-an-organization). | +| `data.attributes.global-provider-sharing` | boolean | false | If true, providers in the organization's private provider repository will be available to all other organizations in this Terraform Enterprise instance. Enabling this will disable any previously configured [provider consumers](#list-provicer-consumers-for-an-organization). | +| `data.attributes.is-disabled` | boolean | false | Removes all permissions from the organization and makes it inaccessible to users. | +| `data.attributes.apply-timeout` | string | 24h | Maximum run time for Terraform applies for this organization. Will use the configured global defaults if left unset. Specify a duration with a decimal number and a unit suffix. | +| `data.attributes.plan-timeout` | string | 2h | Maximum run time for Terraform plans for this organization. Will use the configured global defaults if left unset. Specify a duration with a decimal number and a unit suffix. | +| `data.attributes.terraform-build-worker-apply-timeout` | string | 24h | Deprecated. Please use `data.attributes.apply-timeout` instead. | +| `data.attributes.terraform-build-worker-plan-timeout` | string | 2h | Deprecated. Please use `data.attributes.plan-timeout` instead. | +| `data.attributes.workspace-limit` | integer | | Maximum number of workspaces for this organization. If this number is set to a value lower than the number of workspaces the organization has, it will prevent additional workspaces from being created, but existing workspaces will not be affected. If set to 0, this limit will have no effect. | + +### Sample Payload + +```json +{ + "data": { + "type": "organizations", + "attributes": { + "global-module-sharing": true + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://tfe.example.com/api/v2/admin/organizations/my-organization +``` + +### Sample Response + +```json +{ + "data": { + "id": "my-organization", + "type": "organizations", + "attributes": { + "access-beta-tools": false, + "external-id": "org-XBiRp755dav5p3P2", + "is-disabled": false, + "name": "my-organization", + "apply-timeout": null, + "plan-timeout": null, + "terraform-worker-sudo-enabled": false, + "notification-email": "my-organization@example.com", + "global-module-sharing": true, + "global-provider-sharing": false, + "sso-enabled": false, + "workspace-limit": null + }, + "relationships": { + "owners": { + "data": [ + { + "id": "user-hxTQDETqnJsi5VYP", + "type": "users" + } + ] + }, + "subscription": { + "data": null + }, + "feature-set": { + "data": null + }, + "module-consumers": { + "links": { + "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers" + } + } + }, + "links": { + "self": "/api/v2/admin/organizations/my-organization" + } + } +} +``` + +## Delete an Organization + +`DELETE /admin/organizations/:name` + +| Parameter | Description | +| --------- | -------------------------------------- | +| `:name` | The name of the organization to delete | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------- | +| [204][] | Empty response | The organization was successfully deleted | +| [404][] | [JSON API error object][] | Organization not found, or client is not an administrator | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://tfe.example.com/api/v2/admin/organizations/my-organization +``` + +## List Module Consumers for an Organization + +-> This API endpoint is available in Terraform Enterprise as of version 202103-1. + +`GET /api/v2/admin/organizations/:name/relationships/module-consumers` + +This endpoint lists specific organizations in the Terraform Enterprise installation that have permission to use an organization's modules. It will be empty if the organization is sharing modules using global module sharing, or if the organization has no module sharing configuration. + +| Parameter | Description | +| --------- | -------------------------------------------------------------------- | +| `:name` | The name of the organization whose module consumers should be listed | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found, or client is not an administrator | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 organizations per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "my-organization", + "type": "organizations", + "attributes": { + "access-beta-tools": false, + "external-id": "org-XBiRp755dav5p3P2", + "is-disabled": false, + "name": "my-organization", + "apply-timeout": null, + "plan-timeout": null, + "terraform-worker-sudo-enabled": false, + "notification-email": "my-organization@example.com", + "global-module-sharing": false, + "global-provider-sharing": false, + "sso-enabled": false, + "workspace-limit": null + }, + "relationships": { + "module-consumers": { + "links": { + "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers" + } + }, + "owners": { + "data": [ + { + "id": "user-hxTQDETqnJsi5VYP", + "type": "users" + } + ] + }, + "subscription": { + "data": null + }, + "feature-set": { + "data": null + } + }, + "links": { + "self": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } + } + ] +} +``` + +## Update an Organization's Module Consumers + +-> This API endpoint is available in Terraform Enterprise as of version 202103-1. + +~> **Note:** This API endpoint is **deprecated** and will be removed in a future release. Transition existing integrations with this API to the [Admin Registry Sharing API](/terraform/enterprise/api-docs/admin/registry-sharing). + +`PATCH /admin/organizations/:name/relationships/module-consumers` + +This endpoint is used to specify a list of organizations that can use modules from the sharing organization's private registry. Setting a list of module consumers will turn off global module sharing for an organization. + +| Parameter | Description | +| --------- | ----------------------------------------------------------- | +| `:name` | The name of the organization whose registry is being shared | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------ | +| [204][] | No content | The list of module consumers was successfully updated | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, module consumer not found, etc..) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which organizations will consume modules. These objects must contain `id` and `type` properties, and the `type` property must be `organizations` (e.g. `{ "id": "an-org", "type": "organizations" }`). | + +### Sample Payload + +```json +{ + "data": [ + { + "id": "an-org", + "type": "organizations" + + }, + { + "id": "another-org", + "type": "organizations" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers +``` + +### Sample Response + +The response body will be empty if successful. + +## List Provider Consumers for an Organization + +-> This API endpoint is available in Terraform Enterprise as of version 202301-1. + +`GET /api/v2/admin/organizations/:name/relationships/provider-consumers` + +This endpoint lists specific organizations in the Terraform Enterprise installation that have permission to use an organization's providers. It will be empty if the organization is sharing providers using global provider sharing, or if the organization has no provider sharing configuration. + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------- | +| `:name` | The name of the organization whose provider consumers should be listed | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found, or client is not an administrator | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 organizations per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "my-organization", + "type": "organizations", + "attributes": { + "access-beta-tools": false, + "external-id": "org-XBiRp755dav5p3P2", + "is-disabled": false, + "name": "my-organization", + "apply-timeout": null, + "plan-timeout": null, + "terraform-worker-sudo-enabled": false, + "notification-email": "my-organization@example.com", + "global-module-sharing": false, + "global-provider-sharing": false, + "sso-enabled": false, + "workspace-limit": null + }, + "relationships": { + "provider-consumers": { + "links": { + "related": "/api/v2/admin/organizations/my-organization/relationships/provider-consumers" + } + }, + "owners": { + "data": [ + { + "id": "user-hxTQDETqnJsi5VYP", + "type": "users" + } + ] + }, + "subscription": { + "data": null + }, + "feature-set": { + "data": null + } + }, + "links": { + "self": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } + } + ] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/registry-sharing.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/registry-sharing.mdx new file mode 100644 index 0000000000..565a5b4e02 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/registry-sharing.mdx @@ -0,0 +1,92 @@ +--- +page_title: /registry-partnerships API reference for Terraform Enterprise +description: >- + Use the `/registry-partnerships` endpoint to configure registry sharing. Learn how to update which organizations can use modules and providers from your private registry using the HTTP API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Registry Partnership API Endpoint + +Admins and operators who install and maintain their organization's Terraform Enterprise instance are able to use the `registry-partnerships` endpoint to configure registry sharing. + +## Introduction + +There are two ways to configure registry sharing via the Admin API: + +- This endpoint, which allows an organization to share modules and providers with a specific list of other organizations. +- The [update an organization endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization), whose `data.attributes.global-module-sharing` and `data.attributes.global-provider-sharing` properties allows an organization to share modules and providers with every organization in the instance. + +Enabling one option will automatically disable the other. For more information, see [Administration: Registry Sharing](/terraform/enterprise/application-administration/registry-sharing). + +## Update an Organization's Provider Partnership + +-> This API endpoint is available in Terraform Enterprise as of version 202301-1. + +`PUT /admin/organizations/:name/registry-partnerships` + +This endpoint sets the list of organizations that can use modules and providers from the sharing organization's private registry. Sharing with specific organizations will automatically turn off global module and/or provider sharing, which is configured with the [update an organization endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization) (via the `data.attributes.global-module-sharing` and `data.attributes.global-provider-sharing` properties). + +| Parameter | Description | +| --------- | ----------------------------------------------------------- | +| `:name` | The name of the organization whose registry is being shared | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------ | +| [204][] | No content | The list of module and provider consumers was successfully updated | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PUT endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------------------------------ | -------------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"registry-partnerships"` | +| `data.attributes.module-consumers` | array\[string] | | A list of organization names that will be able to access modules in the producing organization's registry. | +| `data.attributes.provider-consumers` | array\[string] | | A list of organization names that will be able to access providers in the producing organization's registry. | + +### Sample Payload + +```json +{ + "data": { + "type": "registry-partnerships", + "attributes": { + "module_consumers": ["org1-name"], + "provider_consumers": ["org1-name", "org2-name"] + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PUT \ + --data @payload.json \ + https://tfe.example.com/api/v2/admin/organizations/my-organization/registry-partnerships +``` + +### Sample Response + +The response body will be empty if successful. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/runs.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/runs.mdx new file mode 100644 index 0000000000..780b620006 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/runs.mdx @@ -0,0 +1,224 @@ +--- +page_title: /admin/runs API reference for Terraform Enterprise +description: >- + Use the `/admin/runs` endpoint to interact with Terraform runs. Learn how to list runs and cancel runs using the HTTP API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin Runs API + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + +The Runs Admin API contains endpoints to help site administrators manage runs. + +## List all runs + +`GET /api/v2/admin/runs` + +This endpoint lists all runs in the Terraform Enterprise installation. + +| Status | Response | Reason | +| ------- | -------------------------------------- | ------------------------------- | +| [200][] | [JSON API document][] (`type: "runs"`) | Successfully listed runs | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `q` | **Optional.** A search query string. Runs are searchable by ID, workspace name, organization name or email, and VCS repository identifier. | +| `filter[status]` | **Optional.** A comma-separated list of Run statuses to restrict results to, which can include any of the following: `"pending"`, `"plan_queued"`, `"planning"`, `"planned"`, `"confirmed"`, `"apply_queued"`, `"applying"`, `"applied"`, `"discarded"`, `"errored"`, `"canceled"`, `"cost_estimating"`, `"cost_estimated"`, `"policy_checking"`, `"policy_override"`, `"policy_soft_failed"`, `"policy_checked"`, and `"planned_and_finished"`. | +| `filter[from]` | **Optional.** Must be formatted in RFC 3339 and UTC. | +| `filter[to]` | **Optional.** Must be formatted in RFC 3339 and UTC. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | + +A VCS repository identifier is a reference to a VCS repository in the format `:org/:repo`, where `:org` and `:repo` refer to the organization (or project) and repository in your VCS provider. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/admin/runs" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "run-VCsNJXa59eUza53R", + "type": "runs", + "attributes": { + "status": "pending", + "status-timestamps": { + "planned-at": "2018-03-02T23:42:06+00:00", + "discarded-at": "2018-03-02T23:42:06+00:00" + }, + "has-changes": true, + "created-at": "2018-03-02T23:42:06.651Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-mJtb6bXGybq5zbf3", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/runs/run-VCsNJXa59eUza53R" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/admin/runs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/admin/runs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/admin/runs?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + }, + "status-counts": { + "pending": 1, + "planning": 0, + "planned": 0, + "confirmed": 0, + "applying": 0, + "applied": 0, + "discarded": 0, + "errored": 0, + "canceled": 0, + "policy-checking": 0, + "policy-override": 0, + "policy-checked": 0, + "total": 1 + } + } +} +``` + +## Force a run into the "cancelled" state + +`POST /admin/runs/:id/actions/force-cancel` + +| Parameter | Description | +| --------- | ---------------------------- | +| `:id` | The ID of the run to cancel. | + +This endpoint forces a run (and its plan/apply, if applicable) into the `"canceled"` state. This action should only be performed for runs that are stuck and no longer progressing normally, as there is a risk of lost state data if a progressing apply is force-canceled. Healthy runs can be [requested for cancellation by end-users](/terraform/enterprise/run/states). + +| Status | Response | Reason | +| ------- | -------------------------------------- | ------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "runs"`) | Successfully canceled the run. | +| [404][] | [JSON API error object][] | Run not found, or client is not an administrator. | + +### Request body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ----------------------------------------------------------- | +| `comment` | string | `null` | An optional explanation for why the run was force-canceled. | + +### Sample Payload + +```json +{ + "comment": "This run was stuck and would never finish." +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + "https://app.terraform.io/api/v2/admin/runs/run-VCsNJXa59eUza53R/actions/force-cancel" +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-VCsNJXa59eUza53R", + "type": "runs", + "attributes": { + "status": "errored", + "status-timestamps": { + "planned-at": "2018-03-02T23:42:06Z" + }, + "has-changes": true, + "created-at": "2018-03-02T23:42:06.651Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-mJtb6bXGybq5zbf3", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/runs/run-VCsNJXa59eUza53R" + } + } +} +``` + +### Available Related Resources + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------------------------- | ----------------------------------------------------------- | +| `workspace` | The workspace this run belongs in. | +| `workspace.organization` | The organization of the associated workspace. | +| `workspace.organization.owners` | The owners of the organization of the associated workspace. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/sentinel-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/sentinel-versions.mdx new file mode 100644 index 0000000000..74c34ff625 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/sentinel-versions.mdx @@ -0,0 +1,346 @@ +--- +page_title: /admin/sentinel-versions API reference for Terraform Enterprise +description: >- + Use the `/admin/sentinel-versions` endpoint to manage available Sentinel versions. Learn how to list, show, create, update, and delete Sentinel versions using the HTTP API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin Sentinel Versions API + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + +The Sentinel Versions Admin API lets site administrators manage which versions of Sentinel are available to the HCP Terraform users within their enterprise. + +## List all Sentinel versions + +`GET /api/v2/admin/sentinel-versions` + +This endpoint lists all known versions of Sentinel. + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------- | +| [200][] | [JSON API document][] (`type: "sentinel-versions"`) | Successfully lists Sentinel versions. | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[version]` | **Optional.** A query string. This will find an exact Sentinel version matching the version queried. This option takes precedence over search queries. | +| `search[version]` | **Optional.** A search query string. This will search for Sentinel versions matching the version number queried. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 Sentinel versions per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/admin/sentinel-versions" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "sentinel-versions", + "attributes": { + "version": "0.22.1", + "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip", + "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c", + "deprecated": false, + "deprecated-reason": null, + "official": true, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + } + ], + "links": { + "self": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20", + "last": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=4&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": 2, + "total-pages": 4, + "total-count": 70 + } + } +} +``` + +## Create a Sentinel version + +`POST /api/v2/admin/sentinel-versions` + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | ---------------------------------------------- | +| [201][] | [JSON API document][] (`type: "sentinel-versions"`) | The Sentinel version was successfully created. | +| [404][] | [JSON API error object][] | The client is not an administrator. | +| [422][] | [JSON API error object][] | Validation errors. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"sentinel-versions"`. | +| `data.attributes.version` | string | | A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`). | +| `data.attributes.url` | string | | The URL where you can download the 64-bit Linux binary of this version. | +| `data.attributes.sha` | string | | The SHA-256 checksum of the compressed Sentinel binary. | +| `data.attributes.deprecated` | bool | `false` | Whether or not this version of Sentinel is deprecated. | +| `data.attributes.deprecated-reason` | string | `null` | Additional context about why a version of Sentinel is deprecated. Field is null unless deprecated is `true`. | +| `data.attributes.official` | bool | `false` | Whether or not this is an official release of Sentinel. | +| `data.attributes.enabled` | bool | `true` | Whether or not this version of Sentinel is enabled for use in HCP Terraform. | +| `data.attributes.beta` | bool | `false` | Whether or not this version of Sentinel is a beta pre-release. | + +### Sample Payload + +```json +{ + "data": { + "type": "sentinel-versions", + "attributes": { + "version": "0.22.1", + "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip", + "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c", + "official": true, + "enabled": true, + "beta": false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/sentinel-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "sentinel-versions", + "attributes": { + "version": "0.22.1", + "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip", + "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c", + "official": true, + "deprecated": false, + "deprecated-reason": null, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + } +} +``` + +## Show a Sentinel version + +`GET /api/v2/admin/sentinel-versions/:id` + +| Parameter | Description | +| --------- | --------------------------------------- | +| `:id` | The ID of the Sentinel version to show. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "sentinel-versions"`) | Successfully shows the specified Sentinel version. | +| [404][] | [JSON API error object][] | Could not find the specified Sentinel version, or client is not an administrator. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/admin/sentinel-versions/tool-L4oe7rNwn7J4E5Yr +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "sentinel-versions", + "attributes": { + "version": "0.22.1", + "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip", + "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c", + "official": true, + "deprecated": false, + "deprecated-reason": null, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + } +} +``` + +## Update a Sentinel version + +`PATCH /api/v2/admin/sentinel-versions/:id` + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the Sentinel version to update. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "sentinel-versions"`) | The Sentinel version was successfully updated. | +| [404][] | [JSON API error object][] | Could not find the specified Sentinel version, or client is not an administrator. | +| [422][] | [JSON API error object][] | Validation errors. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ---------------- | --------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"sentinel-versions"`. | +| `data.attributes.version` | string | (previous value) | A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"`, `"0.12.20-beta1"`). | +| `data.attributes.url` | string | (previous value) | The URL you can download the 64-bit Linux binary of this version. | +| `data.attributes.sha` | string | (previous value) | The SHA-256 checksum of the compressed Sentinel binary. | +| `data.attributes.official` | bool | (previous value) | Whether or not this is an official release of Sentinel. | +| `data.attributes.deprecated` | bool | (previous value) | Whether or not this version of Sentinel is deprecated. | +| `data.attributes.deprecated-reason` | string | (previous value) | Additional context about why a version of Sentinel is deprecated. | +| `data.attributes.enabled` | bool | (previous value) | Whether or not this version of Sentinel is enabled for use in HCP Terraform. | +| `data.attributes.beta` | bool | (previous value) | Whether or not this version of Sentinel is a beta pre-release. | + +### Sample Payload + +```json +{ + "data": { + "type": "sentinel-versions", + "attributes": { + "deprecated": true, + "deprecated-reason": "A bug was discovered in this version of Sentinel. Please upgrade as soon as possible" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/sentinel-versions/tool-L4oe7rNwn7J4E5Yr +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "sentinel-versions", + "attributes": { + "version": "0.22.1", + "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip", + "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c", + "official": true, + "deprecated": true, + "deprecated-reason": "A bug was discovered in this version of Sentinel. Please upgrade as soon as possible", + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2023-08-23T22:34:24.561Z" + } + } +} +``` + +## Delete a Sentinel version + +`DELETE /api/v2/admin/sentinel-versions/:id` + +This endpoint removes a Sentinel version from HCP Terraform. You cannot remove officially labeled Sentinel versions or any version used by a workspace. + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the Sentinel version to delete. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| [204][] | Empty response | The Sentinel version was successfully deleted. | +| [404][] | [JSON API error object][] | The request could not find a matching Sentinel version with the specified ID, or the client is not an administrator. | +| [422][] | [JSON API error object][] | The request could not remove the Sentinel version because it is an official version or a workspace uses it. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/admin/sentinel-versions/tool-L4oe7rNwn7J4E5Yr +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/settings.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/settings.mdx new file mode 100644 index 0000000000..c1da765c68 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/settings.mdx @@ -0,0 +1,897 @@ +--- +page_title: /admin/general-settings API reference for Terraform Enterprise +description: >- + Use the `/admin/general-settings` set of endpoints to configure Terraform Enterprise. Learn how to list and update general, customization, cost estimation, SAML, SMTP, and Twilio settings using the HTTP API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents +[JSON API error object]: https://jsonapi.org/format/#error-objects +[speculative plans]: /terraform/enterprise/run/remote-operations#speculative-plans + +# Terraform Enterprise Settings API + +This topic provides reference information for the following endpoints: + +- `/admin/general-settings` +- `/admin/data-retention-policy-settings` +- `/admin/cost-estimation-settings` +- `/admin/saml-settings` +- `/admin/smtp-settings` +- `/admin/twilio-settings` +- `/admin/customization-settings` +- `/admin/oidc-settings` + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + +## List General Settings + +`GET /api/v2/admin/general-settings` + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | ------------------------------------ | +| [200][] | [JSON API document][] (`type: "general-settings"`) | Successfully listed General settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/admin/general-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "general", + "type": "general-settings", + "attributes": { + "limit-user-organization-creation": true, + "api-rate-limiting-enabled": true, + "api-rate-limit": 30, + "plan-timeout": "2h", + "apply-timeout": "24h", + "send-passing-statuses-for-untriggered-speculative-plans": false, + "allow-speculative-plans-on-pull-requests-from-forks": false, + "default-remote-state-access": true + } + } +} +``` + +## Update General Settings + +`PATCH /api/v2/admin/general-settings` + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "general-settings"`) | Successfully updated the General settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.allow-speculative-plans-on-pull-requests-from-forks` | bool | `false` | When set to `false`, [speculative plans][] are not run on pull requests from forks of a repository. It is currently supported for the following VCS providers: GitHub.com, GitHub.com (OAuth), GitHub Enterprise, Bitbucket Cloud, Azure DevOps Server, Azure DevOps Services. To learn more about this setting, refer to the [documentation](/terraform/enterprise/application-administration/general#allow-speculative-plans-on-pull-requests-from-forks) | +| `data.attributes.api-rate-limit` | integer | 30 | The number of allowable API requests per second for any client. This value cannot be less than 30. To learn more about API Rate Limiting, refer to the [rate limiting documentation][] | +| `data.attributes.api-rate-limiting-enabled` | bool | `true` | Whether or not rate limiting is enabled for API requests. To learn more about API Rate Limiting, refer to the [rate limiting documentation][] | +| `data.attributes.default-remote-state-access` | bool | `true` | Determines the default value for the `global-remote-state` attribute on new workspaces. For more details, refer to [Administration: General Settings](/terraform/enterprise/application-administration/general#remote-state-sharing) and [Workspaces API: Create a Workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace). | +| `data.attributes.limit-user-organization-creation` | bool | `true` | When set to `true`, limits the ability to create organizations to users with the `site-admin` permission only. | +| `data.attributes.send-passing-statuses-for-untriggered-speculative-plans` | bool | `false` | When set to `true`, workspaces automatically send passing commit statuses for any pull requests that don't affect their tracked files. | +| `data.attributes.plan-timeout` | string | `2h` | Default maximum run time for Terraform plans. Can be overridden on a per-organization basis. Specify a duration with a decimal number and a unit suffix. | +| `data.attributes.apply-timeout` | string | `24h` | Default maximum run time for Terraform applies. Can be overridden on a per-organization basis. Specify a duration with a decimal number and a unit suffix. | +| `data.attributes.terraform-build-worker-plan-timeout` | string | `2h` | Deprecated. Please use `data.attributes.plan-timeout` instead. | +| `data.attributes.terraform-build-worker-apply-timeout` | string | `24h` | Deprecated. Please use `data.attributes.apply-timeout` instead. | + + +[rate limiting documentation]: /terraform/enterprise/api-docs#rate-limiting + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "limit-user-organization-creation": true, + "api-rate-limiting-enabled": true, + "api-rate-limit": 50, + "plan-timeout": "2h", + "apply-timeout": "24h" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/general-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "general", + "type": "general-settings", + "attributes": { + "limit-user-organization-creation": true, + "api-rate-limiting-enabled": true, + "api-rate-limit": 50, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "allow-speculative-plans-on-pull-requests-from-forks": false, + "plan-timeout": "2h", + "apply-timeout": "24h", + "default-remote-state-access": true + } + } +} +``` + +## Show data retention policy settings + +`GET /api/v2/admin/data-retention-policy-settings` + +This endpoint returns the global data retention policy for all organizations. +When a global data retention policy is not set, organizations retain all backing data by default. +Read more about [admin data retention policy settings](/terraform/enterprise/application-administration/general#data-retention-policies). + +Admin settings only support the [`data-retention-policy-delete-olders`](/terraform/enterprise/api-docs/data-retention-policies#data-retention-policy-delete-olders) policy type. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#show-data-retention-policy) for details. + +## Create or update data retention policy settings + +`POST /api/v2/admin/data-retention-policy-settings` + +This endpoint creates a default data retention policy for all organizations on the site. +When a global data retention policy is not set, organizations retain all backing data by default. +Read more about [admin data retention policy settings](/terraform/enterprise/application-administration/general#data-retention-policies). + +Admin settings only support the [`data-retention-policy-delete-olders`](/terraform/enterprise/api-docs/data-retention-policies#data-retention-policy-delete-olders) policy type. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#create-or-update-data-retention-policy) for details. + +## Remove data retention policy + +`DELETE /api/v2/admin/data-retention-policy-settings` + +This endpoint removes the data retention policy set at the site admin level. +When a data retention policy is not set for the site admin, organizations retain all backing data by default. + +Read more about [admin data retention policy settings](/terraform/enterprise/application-administration/general#data-retention-policies). + +See [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#remove-data-retention-policy) for details. + +## List Cost Estimation Settings + +`GET /api/v2/admin/cost-estimation-settings` + +| Status | Response | Reason | +| ------- | ---------------------------------------------------------- | -------------------------------------------- | +| [200][] | [JSON API document][] (`type: "cost-estimation-settings"`) | Successfully listed Cost Estimation settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/admin/cost-estimation-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "cost-estimation", + "type": "cost-estimation-settings", + "attributes": { + "enabled": true, + "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE", + "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", + "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}", + "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1", + "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1", + "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2", + "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3" + } + } +} +``` + +## Update Cost Estimation Settings + +`PATCH /api/v2/admin/cost-estimation-settings` + +| Status | Response | Reason | +| ------- | ---------------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "cost-estimation-settings"`) | Successfully updated Cost Estimation settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +If `data.attributes.enabled` is set to `true`, there must be at least one set of credentials populated with valid values. For example, either both `aws-access-key-id` and `aws-secret-key` must be set, _or_ `gcp-credentials` must be set. + +See [SAML Configuration](/terraform/enterprise/saml/configuration) for more details on attribute values. + +| Key path | Type | Default | Description | +| --------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.attributes.enabled` | bool | `false` | Allows organizations to opt-in to the Cost Estimation feature. | +| `data.attributes.aws-access-key-id` | string | | An AWS Access Key ID that the Cost Estimation feature will use to authorize to AWS's Pricing API. | +| `data.attributes.aws-secret-key` | string | | An AWS Secret Key that the Cost Estimation feature will use to authorize to AWS's Pricing API. | +| `data.attributes.gcp-credentials` | string | | A JSON string containing GCP credentials that the Cost Estimation feature will use to authorize to the Google Cloud Platform's Pricing API. This must be the contents of a valid JSON key that is downloaded when [creating a Service Account in GCP](https://cloud.google.com/video-intelligence/docs/common/auth#creating_a_service_account_in_the). | +| `data.attributes.azure-client-id` | string | | An Azure Client ID that the Cost Estimation feature will use to authorize to Azure's RateCard API. | +| `data.attributes.azure-client-secret` | string | | An Azure Client Secret that the Cost Estimation feature will use to authorize to Azure's RateCard API. | +| `data.attributes.azure-subscription-id` | string | | An Azure Subscription ID that the Cost Estimation feature will use to authorize to Azure's RateCard API. | +| `data.attributes.azure-tenant-id` | string | | An Azure Tenant ID that the Cost Estimation feature will use to authorize to Azure's RateCard API. | + +```json +{ + "data": { + "attributes": { + "enabled": true, + "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE", + "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", + "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}", + "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1", + "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1", + "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2", + "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/cost-estimation-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "cost-estimation", + "type": "cost-estimation-settings", + "attributes": { + "enabled": true, + "aws-access-key-id": "AKIAIOSFODNN7EXAMPLE", + "aws-secret-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", + "gcp-credentials": "{\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n....=\\n-----END PRIVATE KEY-----\",\"private_key_id\":\"some_id\",...}", + "azure-client-id": "9b516fe8-415s-9119-bab0-EXAMPLEID1", + "azure-client-secret": "9b516fe8-415s-9119-bab0-EXAMPLESEC1", + "azure-subscription-id": "9b516fe8-415s-9119-bab0-EXAMPLEID2", + "azure-tenant-id": "9b516fe8-415s-9119-bab0-EXAMPLEID3" + } + } +} +``` + +## List SAML Settings + +`GET /api/v2/admin/saml-settings` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ----------------------------------- | +| [200][] | [JSON API document][] (`type: "saml-settings"`) | Successfully listed SAML settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/admin/saml-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "saml", + "type": "saml-settings", + "attributes": { + "enabled": true, + "debug": false, + "old-idp-cert": null, + "idp-cert": "SAMPLE-CERTIFICATE", + "slo-endpoint-url": "https://example.com/slo", + "sso-endpoint-url": "https://example.com/sso", + "attr-username": "Username", + "attr-groups": "MemberOf", + "attr-site-admin": "SiteAdmin", + "site-admin-role": "site-admins", + "sso-api-token-session-timeout": 1209600, + "acs-consumer-url": "https://example.com/users/saml/auth", + "metadata-url": "https://example.com/users/saml/metadata" + } + } +} +``` + +## Update SAML Settings + +`PATCH /api/v2/admin/saml-settings` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "saml-settings"`) | Successfully updated SAML settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +If `data.attributes.enabled` is set to `true`, all remaining attributes must have valid values. You can omit attributes if they have a default value, or if a value was set by a previous update. Omitted attributes keep their previous values. + +See [SAML Configuration](/terraform/enterprise/saml/configuration) for more details on attribute values. + +| Key path | Type | Default | Description | +| ----------------------------------------------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.enabled` | bool | `false` | Allows SAML to be used. If true, all remaining attributes must have valid values. | +| `data.attributes.debug` | bool | `false` | Enables a SAML debug dialog that allows an admin to see the SAMLResponse XML and processed values during login. | +| `data.attributes.idp-cert` | string | | Identity Provider Certificate specifies the PEM encoded X.509 Certificate as provided by the IdP configuration. | +| `data.attributes.slo-endpoint-url` | string | | Single Log Out URL specifies the HTTPS endpoint on your IdP for single logout requests. This value is provided by the IdP configuration. | +| `data.attributes.sso-endpoint-url` | string | | Single Sign On URL specifies the HTTPS endpoint on your IdP for single sign-on requests. This value is provided by the IdP configuration. | +| `data.attributes.attr-username` | string | `"Username"` | Username Attribute Name specifies the name of the SAML attribute that determines the user's username. | +| `data.attributes.attr-groups` | string | `"MemberOf"` | Team Attribute Name specifies the name of the SAML attribute that determines team membership. | +| `data.attributes.attr-site-admin` | string | `"SiteAdmin"` | Specifies the role for site admin access. Overrides the "Site Admin Role" method. | +| `data.attributes.site-admin-role` | string | `"site-admins"` | Specifies the role for site admin access, provided in the list of roles sent in the Team Attribute Name attribute. | +| `data.attributes.sso-api-token-session-timeout` | integer | 1209600 | Specifies the Single Sign On session timeout in seconds. Defaults to 14 days. | + +```json +{ + "data": { + "attributes": { + "enabled": true, + "debug": false, + "idp-cert": "NEW-CERTIFICATE", + "slo-endpoint-url": "https://example.com/slo", + "sso-endpoint-url": "https://example.com/sso", + "attr-username": "Username", + "attr-groups": "MemberOf", + "attr-site-admin": "SiteAdmin", + "site-admin-role": "site-admins", + "sso-api-token-session-timeout": 1209600 + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/saml-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "saml", + "type": "saml-settings", + "attributes": { + "enabled": true, + "debug": false, + "old-idp-cert": "SAMPLE-CERTIFICATE", + "idp-cert": "NEW-CERTIFICATE", + "slo-endpoint-url": "https://example.com/slo", + "sso-endpoint-url": "https://example.com/sso", + "attr-username": "Username", + "attr-groups": "MemberOf", + "attr-site-admin": "SiteAdmin", + "site-admin-role": "site-admins", + "sso-api-token-session-timeout": 1209600, + "acs-consumer-url": "https://example.com/users/saml/auth", + "metadata-url": "https://example.com/users/saml/metadata" + } + } +} +``` + +## Revoke previous SAML IdP Certificate + +`POST /api/v2/admin/saml-settings/actions/revoke-old-certificate` + +When reconfiguring the IdP certificate, Terraform Enterprise will retain the old IdP certificate to allow for a rotation period. This PUT endpoint will revoke the older IdP certificate when the new IdP certificate is known to be functioning correctly. + +See [SAML Configuration](/terraform/enterprise/saml/configuration) for more details. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/admin/saml-settings/actions/revoke-old-certificate +``` + +### Sample Response + +```json +{ + "data": { + "id": "saml", + "type": "saml-settings", + "attributes": { + "enabled": true, + "debug": false, + "old-idp-cert": null, + "idp-cert": "NEW-CERTIFICATE", + "slo-endpoint-url": "https://example.com/slo", + "sso-endpoint-url": "https://example.com/sso", + "attr-username": "Username", + "attr-groups": "MemberOf", + "attr-site-admin": "SiteAdmin", + "site-admin-role": "site-admins", + "sso-api-token-session-timeout": 1209600, + "acs-consumer-url": "https://example.com/users/saml/auth", + "metadata-url": "https://example.com/users/saml/metadata" + } + } +} +``` + +## List SMTP Settings + +`GET /api/v2/admin/smtp-settings` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ----------------------------------- | +| [200][] | [JSON API document][] (`type: "smtp-settings"`) | Successfully listed SMTP settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/admin/smtp-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "smtp", + "type": "smtp-settings", + "attributes": { + "enabled": true, + "host": "example.com", + "port": 25, + "sender": "sample_user@example.com", + "auth": "login", + "username": "sample_user" + } + } +} +``` + +## Update SMTP Settings + +`PATCH /api/v2/admin/smtp-settings` + +When a request to this endpoint is submitted, a test message will be sent to the specified `test-email-address`. If the test message delivery fails, the API will return an error code indicating the reason for the failure. + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "smtp-settings"`) | Successfully updated the SMTP settings | +| [401][] | [JSON API error object][] | SMTP user credentials are invalid | +| [404][] | [JSON API error object][] | User unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | SMTP server returned a server error | +| [504][] | [JSON API error object][] | SMTP server timed out | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +If `data.attributes.enabled` is set to `true`, all remaining attributes must have valid values. You can omit attributes if they have a default value, or if a value was set by a previous update. Omitted attributes keep their previous values. + +| Key path | Type | Default | Description | +| ------------------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.enabled` | bool | `false` | Allows SMTP to be used. If true, all remaining attributes must have valid values. | +| `data.attributes.host` | string | | The host address of the SMTP server. | +| `data.attributes.port` | integer | | The port of the SMTP server. | +| `data.attributes.sender` | string | | The desired sender address. | +| `data.attributes.auth` | string | `"none"` | The authentication type. Valid values are `"none"`, `"plain"`, and `"login"`. | +| `data.attributes.username` | string | | The username used to authenticate to the SMTP server. Only required if `data.attributes.auth` is set to `"login"` or `"plain"`. | +| `data.attributes.password` | string | | The username used to authenticate to the SMTP server. Only required if `data.attributes.auth` is set to `"login"` or `"plain"`. | +| `data.attributes.test-email-address` | string | | The email address to send a test message to. Not persisted and only used during testing. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "enabled": true, + "host": "example.com", + "port": 25, + "sender": "sample_user@example.com", + "auth": "login", + "username": "sample_user", + "password": "sample_password", + "test-email-address": "test@example.com" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/smtp-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "smtp", + "type": "smtp-settings", + "attributes": { + "enabled": true, + "host": "example.com", + "port": 25, + "sender": "sample_user@example.com", + "auth": "login", + "username": "sample_user" + } + } +} +``` + +## List Twilio Settings + +`GET /api/v2/admin/twilio-settings` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | ----------------------------------- | +| [200][] | [JSON API document][] (`type: "twilio-settings"`) | Successfully listed Twilio settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/admin/twilio-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "twilio", + "type": "twilio-settings", + "attributes": { + "enabled": true, + "account-sid": "12345abcd", + "from-number": "555-555-5555" + } + } +} +``` + +## Update Twilio Settings + +`PATCH /api/v2/admin/twilio-settings` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "twilio-settings"`) | Successfully listed Twilio settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +If `data.attributes.enabled` is set to `true`, all remaining attributes must have valid values. You can omit attributes if they have a default value, or if a value was set by a previous update. Omitted attributes keep their previous values. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | ----------------------------------------------------------------------------------- | +| `data.attributes.enabled` | bool | `false` | Allows Twilio to be used. If true, all remaining attributes must have valid values. | +| `data.attributes.account-sid` | string | | The Twilio account id. | +| `data.attributes.auth-token` | string | | The Twilio authentication token. | +| `data.attributes.from-number` | string | | The Twilio registered phone number that will be used to send the message. | + +```json +{ + "data": { + "attributes": { + "enabled": true, + "account-sid": "12345abcd", + "auth-token": "sample_token", + "from-number": "555-555-5555" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/twilio-settings +``` + +### Sample Response + +```json +{ + "data": { + "id": "twilio", + "type": "twilio-settings", + "attributes": { + "enabled": true, + "account-sid": "12345abcd", + "from-number": "555-555-5555" + } + } +} +``` + +## Verify Twilio Settings + +`POST /api/v2/admin/twilio-settings/verify` + +Uses the `test-number` attribute to send a test SMS when Twilio is enabled. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [200][] | none | Twilio test message sent successfully | +| [400][] | [JSON API error object][] | Verification settings invalid (missing test number, Twilio disabled, etc.) | +| [404][] | [JSON API error object][] | User unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | ------------------------------------------------------------------------------------- | +| `data.attributes.test-number` | string | | The target phone number for the test SMS. Not persisted and only used during testing. | + +```json +{ + "data": { + "attributes": { + "test-number": "555-555-0000" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/twilio-settings/verify +``` + +## List Customization Settings + +`GET /api/v2/admin/customization-settings` + +-> This API endpoint is available in Terraform Enterprise as of version 202003-1. + +| Status | Response | Reason | +| ------- | -------------------------------------------------------- | ------------------------------------------ | +| [200][] | [JSON API document][] (`type: "customization-settings"`) | Successfully listed Customization settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/admin/customization-settings +``` + +### Sample Response + +Note that the `support-email-address` attribute in the following example returns `support@hashicorp.com`, which is a not a functional email address. If you need assistance, visit the [HashiCorp support page](https://support.hashicorp.com/hc/en-us) and open a ticket. + +```json +{ + "data": { + "id": "customization", + "type": "customization-settings", + "attributes": { + "support-email-address": "support@hashicorp.com", + "login-help": "", + "footer": "", + "error": "", + "new-user": "" + } + } +} +``` + +## Update Customization Settings + +`PATCH /api/v2/admin/customization-settings` + +| Status | Response | Reason | +| ------- | -------------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "customization-settings"`) | Successfully updated the Customization settings | +| [404][] | [JSON API error object][] | User unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------------------------------------- | ------ | ------------------------- | --------------------------------------------------------------------------------------------- | +| `data.attributes.support-email-address` | string | `"support@hashicorp.com"`

Note that this is a non-functional address. If you need assistance, visit the [HashiCorp support page](https://support.hashicorp.com/hc/en-us) and open a ticket.

| The deprecated support address for outgoing emails. | +| `data.attributes.login-help` | string | `""` | The login help text presented to users on the login page. | +| `data.attributes.footer` | string | `""` | Custom footer content that is added to the application. | +| `data.attributes.error` | string | `""` | Error instruction content that is presented to users upon unexpected errors. | +| `data.attributes.new-user` | string | `""` | New user instructions that is presented when the user is not yet attached to an organization. | + +### Sample Payload + +In the following example, the `support-email-address` attribute specifies `support@hashicorp.com`, which is not a functional email address. If you need assistance, visit the [HashiCorp support page](https://support.hashicorp.com/hc/en-us) and open a ticket. + +```json +{ + "data": { + "attributes": { + "support-email-address": "support@hashicorp.com", + "login-help": "
Login Help
", + "footer": "

Custom Footer Content

", + "error": "Custom Error Instructions", + "new-user": "New user? Click Here" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/customization-settings +``` + +### Sample Response + +In the following example, the `support-email-address` attribute specifies `support@hashicorp.com`, which is a not a functional address. If you need assistance, visit the [HashiCorp support page](https://support.hashicorp.com/hc/en-us) and open a ticket. + +```json +{ + "data": { + "id": "customization", + "type": "customization-settings", + "attributes": { + "support-email-address": "support@hashicorp.com", + "login-help": "\u003cdiv\u003eLogin Help\u003c/div\u003e", + "footer": "\u003cp\u003eCustom Footer Content\u003c/p\u003e", + "error": "\u003cem\u003eCustom Error Instructions\u003c/em\u003e", + "new-user": "New user? \u003ca href=\"#\"\u003eClick Here\u003c/a\u003e" + } + } +} +``` + +## Rotate OIDC Signing Key + +`POST /api/v2/admin/oidc-settings/actions/rotate-key` + +This endpoint rotates the OIDC signing key used for signing tokens issued for [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials). This key automatically rotates every 90 days, hitting this endpoint resets this timer. Hitting this endpoint has _no effect_ on the next trim time. This endpoint should only be used if a leak of the key is suspected. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [204][] | none | Successfully rotated key | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/admin/oidc-settings/actions/rotate-key +``` + +## Trim OIDC Signing Key + +`POST /api/v2/admin/oidc-settings/actions/trim-key` + +This endpoint trims the OIDC signing key used for signing tokens issued for [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials). This key automatically trims old versions 30 days after the last rotation, hitting this endpoint resets this timer. Hitting this endpoint has _no effect_ on the next rotation time. This endpoint should only be used after rotating the key if a leak of the key is suspected. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [204][] | none | Successfully trimmed key | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/admin/oidc-settings/actions/trim-key +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/terraform-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/terraform-versions.mdx new file mode 100644 index 0000000000..d96eeff064 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/terraform-versions.mdx @@ -0,0 +1,363 @@ +--- +page_title: /admin/terraform-versions API reference for Terraform Enterprise +description: >- + Use the `/admin/terraform-versions` endpoint to manage available Terraform versions. Learn how to list, show, create, update, and delete Terraform versions using the HTTP API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin Terraform Versions API + +The `/admin/terraform-versions` API endpoint lets site administrators manage which versions of Terraform are available to use for Terraform operations. + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + + +## List all Terraform versions + +`GET /api/v2/admin/terraform-versions` + +This endpoint lists all known versions of Terraform. + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------- | +| [200][] | [JSON API document][] (`type: "terraform-versions"`) | Successfully listed Terraform versions | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[version]` | **Optional.** A query string. This will find an exact Terraform version matching the version queried. This option takes precedence over search queries. | +| `search[version]` | **Optional.** A search query string. This will search for Terraform versions matching the version number queried. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 Terraform versions per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/admin/terraform-versions" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "terraform-versions", + "attributes": { + "version": "0.11.8", + "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip", + "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7", + "deprecated": false, + "deprecated-reason": null, + "official": true, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2018-08-15T22:34:24.561Z" + } + }, + { + "id": "tool-qcbYn12vuRKPgPpy", + "type": "terraform-versions", + "attributes": { + "version": "0.11.7", + "url": "https://releases.hashicorp.com/terraform/0.11.7/terraform_0.11.7_linux_amd64.zip", + "sha": "6b8ce67647a59b2a3f70199c304abca0ddec0e49fd060944c26f666298e23418", + "deprecated": false, + "deprecated-reason": null, + "official": true, + "enabled": true, + "beta": false, + "usage": 2, + "created-at": null + } + } + ], + "links": { + "self": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20", + "last": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=4&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": 2, + "total-pages": 4, + "total-count": 70 + } + } +} +``` + +## Create a Terraform version + +`POST /api/v2/admin/terraform-versions` + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | ---------------------------------------------- | +| [201][] | [JSON API document][] (`type: "terraform-versions"`) | The Terraform version was successfully created | +| [404][] | [JSON API error object][] | Client is not an administrator | +| [422][] | [JSON API error object][] | Validation errors | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"terraform-versions"` | +| `data.attributes.version` | string | | A semantic version string in N.N.N or N.N.N-bundleName format (e.g. `"0.11.0"`, `"0.12.20-beta1"`.) | +| `data.attributes.url` | string | | The URL where a ZIP-compressed 64-bit Linux binary of this version can be downloaded | +| `data.attributes.sha` | string | | The SHA-256 checksum of the compressed Terraform binary | +| `data.attributes.deprecated` | bool | `false` | Whether or not this version of Terraform is deprecated | +| `data.attributes.deprecated-reason` | string | `null` | Additional context about why a version of Terraform is deprecated. Field is null unless deprecated is true. | +| `data.attributes.official` | bool | `false` | Whether or not this is an official release of Terraform | +| `data.attributes.enabled` | bool | `true` | Whether or not this version of Terraform is enabled for use in HCP Terraform | +| `data.attributes.beta` | bool | `false` | Whether or not this version of Terraform is a beta pre-release | + +### Sample Payload + +```json +{ + "data": { + "type": "terraform-versions", + "attributes": { + "version": "0.11.8", + "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip", + "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7", + "official": true, + "enabled": true, + "beta": false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/terraform-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "terraform-versions", + "attributes": { + "version": "0.11.8", + "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip", + "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7", + "official": true, + "deprecated": false, + "deprecated-reason": null, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2018-08-15T22:34:24.561Z" + } + } +} +``` + +## Show a Terraform version + +`GET /api/v2/admin/terraform-versions/:id` + +| Parameter | Description | +| --------- | --------------------------------------- | +| `:id` | The ID of the Terraform version to show | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "terraform-versions"`) | The request was successful | +| [404][] | [JSON API error object][] | Terraform version not found, or client is not an administrator | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "terraform-versions", + "attributes": { + "version": "0.11.8", + "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip", + "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7", + "official": true, + "deprecated": false, + "deprecated-reason": null, + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2018-08-15T22:34:24.561Z" + } + } +} +``` + +## Update a Terraform version + +`PATCH /api/v2/admin/terraform-versions/:id` + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the Terraform version to update | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "terraform-versions"`) | The Terraform version was successfully updated | +| [404][] | [JSON API error object][] | Terraform version not found, or client is not an administrator | +| [422][] | [JSON API error object][] | Validation errors | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ---------------- | --------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"terraform-versions"` | +| `data.attributes.version` | string | (previous value) | A semantic version string in N.N.N or N.N.N-bundleName format (e.g. `"0.11.0"`, `"0.12.20-beta1"`.) | +| `data.attributes.url` | string | (previous value) | The URL where a ZIP-compressed 64-bit Linux binary of this version can be downloaded | +| `data.attributes.sha` | string | (previous value) | The SHA-256 checksum of the compressed Terraform binary | +| `data.attributes.official` | bool | (previous value) | Whether or not this is an official release of Terraform | +| `data.attributes.deprecated` | bool | (previous value) | Whether or not this version of Terraform is deprecated | +| `data.attributes.deprecated-reason` | string | (previous value) | Additional context about why a version of Terraform is deprecated. | +| `data.attributes.enabled` | bool | (previous value) | Whether or not this version of Terraform is enabled for use in HCP Terraform | +| `data.attributes.beta` | bool | (previous value) | Whether or not this version of Terraform is a beta pre-release | + +### Sample Payload + +```json +{ + "data": { + "type": "terraform-versions", + "attributes": { + "deprecated": true, + "deprecated-reason": "A bug was discovered in this version of Terraform. Please upgrade as soon as possible" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr +``` + +### Sample Response + +```json +{ + "data": { + "id": "tool-L4oe7rNwn7J4E5Yr", + "type": "terraform-versions", + "attributes": { + "version": "0.11.8", + "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip", + "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7", + "official": true, + "deprecated": true, + "deprecated-reason": "A bug was discovered in this version of Terraform. Please upgrade as soon as possible", + "enabled": true, + "beta": false, + "usage": 0, + "created-at": "2018-08-15T22:34:24.561Z" + } + } +} +``` + +## Delete a Terraform version + +`DELETE /api/v2/admin/terraform-versions/:id` + +This endpoint removes a Terraform version from HCP Terraform. Versions cannot be removed if they are labeled as official versions of Terraform or if there are workspaces using them. + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the Terraform version to delete | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | Empty response | The Terraform version was successfully deleted | +| [404][] | [JSON API error object][] | Terraform version not found, or client is not an administrator | +| [422][] | [JSON API error object][] | The Terraform version cannot be removed (it is official or is in use) | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/users.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/users.mdx new file mode 100644 index 0000000000..f71cc4ab6b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/users.mdx @@ -0,0 +1,509 @@ +--- +page_title: /admin/users API reference for Terraform Enterprise +description: >- + Use the `/admin/users` endpoint to manage users. Learn how to list, delete, suspend, re-activate, and impersonate users, grant and revoke administrative privileges, and disable 2FA. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin Users API + +The `admin/users` API contains endpoints to help site administrators manage user accounts. + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + +## List all users + +`GET /api/v2/admin/users` + +This endpoint lists all user accounts in the Terraform Enterprise installation. + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Successfully listed users | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Users are searchable by username and email address. | +| `filter[admin]` | **Optional.** Can be `"true"` or `"false"` to show only administrators or non-administrators. | +| `filter[suspended]` | **Optional.** Can be `"true"` or `"false"` to show only suspended users or users who are not suspended. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 users per page. | + +### Available Related Resources + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| --------------- | ------------------------------------------------------ | +| `organizations` | A list of organizations that each user is a member of. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/admin/users" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "user-ZL4MsEKnd6iTigTb", + "type": "users", + "attributes": { + "username": "myuser", + "email": "myuser@example.com", + "avatar-url": "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm", + "is-admin": true, + "is-suspended": false, + "is-service-account": false + }, + "relationships": { + "organizations": { + "data": [ + { + "id": "my-organization", + "type": "organizations" + } + ] + } + }, + "links": { + "self": "/api/v2/users/myuser" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + }, + "status-counts": { + "total": 1, + "suspended": 0, + "admin": 1 + } + } +} +``` + +## Delete a user account + +`DELETE /admin/users/:id` + +This endpoint deletes a user's account from Terraform Enterprise. To prevent unowned organizations, a user cannot be deleted if they are the sole owner of any organizations. The organizations must be given a new owner or deleted first. + +| Parameter | Description | +| --------- | ----------------------------- | +| `:id` | The ID of the user to delete. | + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------------------------------- | +| [204][] | Empty body | Successfully removed the user account. | +| [404][] | [JSON API error object][] | Client is not an administrator. | +| [422][] | [JSON API error object][] | The user cannot be deleted because they are the sole owner of one or more organizations. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + "https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb" +``` + +## Suspend a user + +`POST /admin/users/:id/actions/suspend` + +| Parameter | Description | +| --------- | ------------------------------ | +| `:id` | The ID of the user to suspend. | + +This endpoint suspends a user's account, preventing them from authenticating and accessing resources. + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------ | +| [200][] | [JSON API document][] (`type: "users"`) | Successfully suspended the user's account. | +| [400][] | [JSON API error object][] | User is already suspended. | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + "https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/suspend" +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-ZL4MsEKnd6iTigTb", + "type": "users", + "attributes": { + "username": "myuser", + "email": "myuser@example.com", + "avatar-url": "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm", + "is-admin": false, + "is-suspended": true, + "is-service-account": false + }, + "relationships": { + "organizations": { + "data": [ + { + "id": "my-organization", + "type": "organizations" + } + ] + } + }, + "links": { + "self": "/api/v2/users/myuser" + } + } +} +``` + +## Re-activate a suspended user + +`POST /admin/users/:id/actions/unsuspend` + +| Parameter | Description | +| --------- | ---------------------------------- | +| `:id` | The ID of the user to re-activate. | + +This endpoint re-activates a suspended user's account, allowing them to resume authenticating and accessing resources. + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Successfully re-activated the user's account. | +| [400][] | [JSON API error object][] | User is not suspended. | +| [404][] | [JSON API error object][] | User not found, or client is not an administrator. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + "https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/unsuspend" +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-ZL4MsEKnd6iTigTb", + "type": "users", + "attributes": { + "username": "myuser", + "email": "myuser@example.com", + "avatar-url": "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm", + "is-admin": false, + "is-suspended": false, + "is-service-account": false + }, + "relationships": { + "organizations": { + "data": [ + { + "id": "my-organization", + "type": "organizations" + } + ] + } + }, + "links": { + "self": "/api/v2/users/myuser" + } + } +} +``` + +## Grant a user administrative privileges + +`POST /admin/users/:id/actions/grant_admin` + +| Parameter | Description | +| --------- | -------------------------------------------- | +| `:id` | The ID of the user to make an administrator. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Successfully made the user an administrator. | +| [400][] | [JSON API error object][] | User is already an administrator. | +| [404][] | [JSON API error object][] | User not found, or client is not an administrator. | +| [422][] | [JSON API error object][] | Validation errors | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + "https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/grant_admin" +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-ZL4MsEKnd6iTigTb", + "type": "users", + "attributes": { + "username": "myuser", + "email": "myuser@example.com", + "avatar-url": "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm", + "is-admin": true, + "is-suspended": false, + "is-service-account": false + }, + "relationships": { + "organizations": { + "data": [ + { + "id": "my-organization", + "type": "organizations" + } + ] + } + }, + "links": { + "self": "/api/v2/users/myuser" + } + } +} +``` + +## Revoke an user's administrative privileges + +`POST /admin/users/:id/actions/revoke_admin` + +| Parameter | Description | +| --------- | -------------------------------------- | +| `:id` | The ID of the administrator to demote. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Successfully made the user an administrator. | +| [400][] | [JSON API error object][] | User is not an administrator. | +| [404][] | [JSON API error object][] | User not found, or client is not an administrator. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + "https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/revoke_admin" +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-ZL4MsEKnd6iTigTb", + "type": "users", + "attributes": { + "username": "myuser", + "email": "myuser@example.com", + "avatar-url": "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm", + "is-admin": false, + "is-suspended": false, + "is-service-account": false + }, + "relationships": { + "organizations": { + "data": [ + { + "id": "my-organization", + "type": "organizations" + } + ] + } + }, + "links": { + "self": "/api/v2/users/myuser" + } + } +} +``` + +## Disable a user's two-factor authentication + +`POST /admin/users/:id/actions/disable_two_factor` + +| Parameter | Description | +| --------- | -------------------------------------- | +| `:id` | The ID of the user to disable 2FA for. | + +This endpoint disables a user's two-factor authentication in the situation where they have lost access to their device and recovery codes. Before disabling a user's two-factor authentication, completing a security verification process is recommended to ensure the request is legitimate. + +| Status | Response | Reason | +| ------- | --------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Successfully disabled the user's two-factor authentication. | +| [400][] | [JSON API error object][] | User does not have two-factor authentication enabled. | +| [404][] | [JSON API error object][] | User not found, or client is not an administrator. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + "https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/disable_two_factor" +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-ZL4MsEKnd6iTigTb", + "type": "users", + "attributes": { + "username": "myuser", + "email": "myuser@example.com", + "avatar-url": "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm", + "is-admin": false, + "is-suspended": false, + "is-service-account": false + }, + "relationships": { + "organizations": { + "data": [ + { + "id": "my-organization", + "type": "organizations" + } + ] + } + }, + "links": { + "self": "/api/v2/users/myuser" + } + } +} +``` + +## Impersonate another user + +`POST /admin/users/:id/actions/impersonate` + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the user to impersonate. It is not possible to impersonate service accounts or your own account. | + +[impersonate-ui]: /terraform/enterprise/application-administration/resources#impersonating-a-user + +Impersonation allows an admin to begin a new session as another user in the system; for more information, see [Impersonating a User][impersonate-ui] in the Terraform Enterprise administration section. + +-> **Note:** Impersonation is [intended as a UI feature][impersonate-ui], and this endpoint exists to support that UI. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------- | +| [204][] | Empty body | Successfully impersonated the user. | +| [400][] | [JSON API error object][] | A reason for impersonation is required. | +| [403][] | [JSON API error object][] | Client is already impersonating another user. | +| [403][] | [JSON API error object][] | User cannot be impersonated. | +| [404][] | [JSON API error object][] | User not found, or client is not an administrator. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| -------- | ------ | ------- | -------------------------------------------------------------------- | +| `reason` | string | | A reason for impersonation, which will be recorded in the Audit Log. | + +### Sample Payload + +```json +{ + "reason": "Reason for impersonation" +} +``` + +### Sample Request + +```shell +curl \ + --header "Cookie: $COOKIE" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/impersonate +``` + +## End an impersonation session + +`POST /admin/users/actions/unimpersonate` + +When an admin has used the above endpoint to begin an impersonation session, they can make a request to this endpoint, using the cookie provided originally, in order to end that session and log out as the impersonated user. + +This endpoint does not respond with a body, but the response does include a `Set-Cookie` header to persist a new session as the original admin user. As such, this endpoint will have no effect unless the client is able to persist and use cookies. + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------- | +| [204][] | Empty body | Successfully ended the impersonation session. | +| [400][] | [JSON API error object][] | Client is not in an impersonation session. | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Sample Request + +```shell +curl \ + --header "Cookie: $COOKIE" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/admin/users/actions/unimpersonate +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/workspaces.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/workspaces.mdx new file mode 100644 index 0000000000..d93bd702c0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/admin/workspaces.mdx @@ -0,0 +1,252 @@ +--- +page_title: /admin/workspaces API reference for Terraform Enterprise +description: >- + Use the `/admin/workspaces` endpoint to manage workspaces. Learn how to list, show, and destroy workspaces using the HTTP API. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Admin Workspaces API + +The `admin/workspaces` API contains endpoints to help site administrators manage workspaces. + +-> **Terraform Enterprise Only:** The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance. + +## List all workspaces + +`GET /api/v2/admin/workspaces` + +This endpoint lists all workspaces in the Terraform Enterprise installation. + +| Status | Response | Reason | +| ------- | -------------------------------------------- | ------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully listed workspaces | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `q` | **Optional.** A search query string. Workspaces are searchable by name and organization name. | +| `filter[current_run][status]` | **Optional.** A comma-separated list of Run statuses to restrict results to, which can include any of the following: `"pending"`, `"plan_queued"`, `"planning"`, `"planned"`, `"confirmed"`, `"apply_queued"`, `"applying"`, `"applied"`, `"discarded"`, `"errored"`, `"canceled"`, `"cost_estimating"`, `"cost_estimated"`, `"policy_checking"`, `"policy_override"`, `"policy_soft_failed"`, `"policy_checked"`, and `"planned_and_finished"`. | +| `sort` | **Optional.** Allows sorting the organization's workspaces by a provided value. You can sort by `"name"`, `"current-run.created-at"` (the time of the current run), and `"latest-change-at"` (the creation time of the latest state version or the workspace itself if no state version exists). Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable.| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | + +### Available Related Resources + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| --------------------- | -------------------------------------------------------------- | +| `organization` | The organization for each returned workspace. | +| `organization.owners` | A list of owners for each workspace's associated organization. | +| `current_run` | The current run for each returned workspace. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/admin/workspaces" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces", + "attributes": { + "name": "my-workspace", + "locked": false, + "vcs-repo": { + "identifier": "my-organization/my-repository" + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "current-run": { + "data": { + "id": "run-jm8ekSaW3F52FACN", + "type": "runs" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + ], + "links": { + "self": "http://localhost:3000/api/v2/admin/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "http://localhost:3000/api/v2/admin/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "http://localhost:3000/api/v2/admin/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 0, + "total-count": 1 + }, + "status-counts": { + "pending": 1, + "planning": 0, + "planned": 0, + "confirmed": 0, + "applying": 0, + "applied": 0, + "discarded": 0, + "errored": 0, + "canceled": 0, + "policy-checking": 0, + "policy-override": 0, + "policy-checked": 0, + "none": 0, + "total": 1, + } + } +} +``` + +## Show a workspace + +`GET /api/v2/admin/workspaces/:id` + +This endpoint returns the workspace with the specified `workspace_id`. + +| Status | Response | Reason | +| ------- | -------------------------------------------- | ------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully listed workspaces | +| [404][] | [JSON API error object][] | Client is not an administrator. | + +### Query Parameters + +| Parameter | Description | +| --------------- | ---------------- | +| `:workspace_id` | The workspace ID | + +### Available Related Resources + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| --------------------- | -------------------------------------------------------------- | +| `organization` | The organization for each returned workspace. | +| `organization.owners` | A list of owners for each workspace's associated organization. | +| `current_run` | The current run for each returned workspace. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/admin/workspaces/ws-2HRvNs49EWPjDqT1" +``` + +### Sample Response + +```json +{ + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces", + "attributes": { + "name": "my-workspace", + "locked": false, + "vcs-repo": { + "identifier": "my-organization/my-repository" + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "current-run": { + "data": { + "id": "run-jm8ekSaW3F52FACN", + "type": "runs" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } +} +``` + +## Destroy a workspace + +`DELETE /admin/workspaces/:id` + +| Parameter | Description | +| --------------- | ---------------- | +| `:workspace_id` | The workspace ID | + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------- | +| [204][] | | The workspace was successfully destroyed | +| [404][] | [JSON API error object][] | Workspace not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/admin/workspaces/ws-2HRvNs49EWPjDqT1 +``` + +### Sample Response + +The response body will be empty if successful. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/agent-tokens.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/agent-tokens.mdx new file mode 100644 index 0000000000..e1d27c1395 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/agent-tokens.mdx @@ -0,0 +1,272 @@ +--- +page_title: /authentication-tokens API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/authentication-tokens` endpoint to manage + agent tokens. Learn how to read, create, and destroy agent tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Agent token API reference + + + +@include 'tfc-package-callouts/agents.mdx' + + + +## List Agent Tokens + +`GET /agent-pools/:agent_pool_id/authentication-tokens` + +| Parameter | Description | +| ---------------- | ------------------------- | +| `:agent_pool_id` | The ID of the Agent Pool. | + +The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ---------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 tokens per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "at-bonpPzYqv2bGD7vr", + "type": "authentication-tokens", + "attributes": { + "created-at": "2020-08-07T19:38:20.868Z", + "last-used-at": "2020-08-07T19:40:55.139Z", + "description": "asdfsdf", + "token": null + }, + "relationships": { + "created-by": { + "data": { + "id": "user-Nxv6svuhVrTW7eb1", + "type": "users" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show an Agent Token + +`GET /authentication-tokens/:id` + +| Parameter | Description | +| --------- | --------------------------------- | +| `:id` | The ID of the Agent Token to show | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | Success | +| [404][] | [JSON API error object][] | Agent Token not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/authentication-tokens/at-bonpPzYqv2bGD7vr +``` + +### Sample Response + +```json +{ + "data": { + "id": "at-bonpPzYqv2bGD7vr", + "type": "authentication-tokens", + "attributes": { + "created-at": "2020-08-07T19:38:20.868Z", + "last-used-at": "2020-08-07T19:40:55.139Z", + "description": "test token", + "token": null + }, + "relationships": { + "created-by": { + "data": { + "id": "user-Nxv6svuhVrTW7eb1", + "type": "users" + } + } + } + } +} +``` + +## Create an Agent Token + +`POST /agent-pools/:agent_pool_id/authentication-tokens` + +| Parameter | Description | +| ---------------- | ------------------------ | +| `:agent_pool_id` | The ID of the Agent Pool | + +This endpoint returns the secret text of the created authentication token. A token is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | Agent Pool not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during Agent Token creation | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | ------------------------------------ | +| `data.type` | string | | Must be `"authentication-tokens"`. | +| `data.attributes.description` | string | | The description for the Agent Token. | + +### Sample Payload + +```json +{ + "data": { + "type": "authentication-tokens", + "attributes": { + "description":"api" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": { + "id": "at-2rG2oYU9JEvfaqji", + "type": "authentication-tokens", + "attributes": { + "created-at": "2020-08-10T22:29:21.907Z", + "last-used-at": null, + "description": "api", + "token": "eHub7TsW7fz7LQ.atlasv1.cHGFcvf2VxVfUH4PZ7UNdaGB6SjyKWs5phdZ371zkI2KniZs2qKgrAcazhlsiy02awk" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-Nxv6svuhVrTW7eb1", + "type": "users" + } + } + } + } +} +``` + +## Destroy an Agent Token + +`DELETE /api/v2/authentication-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------------------- | +| `:id` | The ID of the Agent Token to destroy. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | Empty response | The Agent Token was successfully destroyed | +| [404][] | [JSON API error object][] | Agent Token not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/agents.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/agents.mdx new file mode 100644 index 0000000000..58acfa2aad --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/agents.mdx @@ -0,0 +1,637 @@ +--- +page_title: /agents and /agent-pools API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/agents` endpoint to read and delete + agents. Use the `/agent-pools` endpoint to read, create, update, and delete + agent pools. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Agents and agent pools API reference + +An Agent Pool represents a group of Agents, often related to one another by sharing a common network segment or purpose. +A workspace may be configured to use one of the organization's agent pools to run remote operations with isolated, +private, or on-premises infrastructure. + + + +@include 'tfc-package-callouts/agents.mdx' + + + +## List Agent Pools + +`GET /organizations/:organization_name/agent-pools` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:organization_name` | The name of the organization. | + +This endpoint allows you to list agent pools, their agents, and their tokens for an organization. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ---------------------- | +| [200][] | [JSON API document][] (`type: "agent-pools"`) | Success | +| [404][] | [JSON API error object][] | Organization not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | +| `q` | **Optional.** A search query string. Agent pools are searchable by name. | | +| `sort` | **Optional.** Allows sorting the returned agents pools. Valid values are `"name"` and `"created-at"`. Prepending a hyphen to the sort parameter will reverse the order (e.g. `"-name"`). | | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agent pools per page. | | +| `filter[allowed_workspaces][name]` | **Optional.** Filters agent pools to those associated with the given workspace. The workspace must have permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). | | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/agent-pools +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "created-at": "2020-08-05T18:10:26.964Z", + "organization-scoped": false, + "agent-count": 3 + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-9EEkcEQSA3XgWyGe", + "type": "workspaces" + } + ] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + }, + "status-counts": { + "total": 1, + "matching": 1 + } + } +} +``` + +## List Agents + +`GET /agent-pools/:agent_pool_id/agents` + +| Parameter | Description | +| ---------------- | --------------------------------- | +| `:agent_pool_id` | The ID of the Agent Pool to list. | + +| Status | Response | Reason | +| ------- | ---------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "agents"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------------- | ---------------------------------------------------------------------------- | +| `filter[last-ping-since]` | **Optional.** Accepts a date in ISO8601 format (ex. `2020-08-11T10:41:23Z`). | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agents per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/agents +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "agent-A726QeosTCpCumAs", + "type": "agents", + "attributes": { + "name": "my-cool-agent", + "status": "idle", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-10-09T18:52:25.246Z" + }, + "links": { + "self": "/api/v2/agents/agent-A726QeosTCpCumAs" + } + }, + { + "id": "agent-4cQzjbr1cnM6Pcxr", + "type": "agents", + "attributes": { + "name": "my-other-cool-agent", + "status": "exited", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-08-12T15:25:09.726Z" + }, + "links": { + "self": "/api/v2/agents/agent-4cQzjbr1cnM6Pcxr" + } + }, + { + "id": "agent-yEJjXQCucpNxtxd2", + "type": "agents", + "attributes": { + "name": null, + "status": "errored", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-08-11T06:22:20.300Z" + }, + "links": { + "self": "/api/v2/agents/agent-yEJjXQCucpNxtxd2" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 3 + } + } +} +``` + +## Show an Agent Pool + +`GET /agent-pools/:id` + +| Parameter | Description | +| --------- | -------------------------------- | +| `:id` | The ID of the Agent Pool to show | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "agent-pools"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd +``` + +### Sample Response + +```json +{ + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "created-at": "2020-08-05T18:10:26.964Z", + "organization-scoped": false + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-9EEkcEQSA3XgWyGe", + "type": "workspaces" + } + ] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i" + } + } +} +``` + +## Show an Agent + +`GET /agents/:id` + +| Parameter | Description | +| --------- | --------------------------- | +| `:id` | The ID of the agent to show | + +| Status | Response | Reason | +| ------- | ---------------------------------------- | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "agents"`) | Success | +| [404][] | [JSON API error object][] | Agent not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ +``` + +### Sample Response + +```json +{ + "data": { + "id": "agent-Zz9PTEcUgBtYzht8", + "type": "agents", + "attributes": { + "name": "my-agent", + "status": "busy", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-09-08T18:47:35.361Z" + }, + "links": { + "self": "/api/v2/agents/agent-Zz9PTEcUgBtYzht8" + } + } +} +``` + +This endpoint lists details about an agent along with that agent's status. [Learn more about agents statuses](/terraform/cloud-docs/agents/agent-pools#view-agent-statuses). + +## Delete an Agent + +`DELETE /agents/:id` + +| Parameter | Description | +| --------- | ----------------------------- | +| `:id` | The ID of the agent to delete | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ | +| [204][] | No Content | Success | +| [412][] | [JSON API error object][] | Agent is not deletable. Agents must have a status of `unknown`, `errored`, or `exited` before being deleted. | +| [404][] | [JSON API error object][] | Agent not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --request DELETE \ + https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ +``` + +## Create an Agent Pool + +`POST /organizations/:organization_name/agent-pools` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:organization_name` | The name of the organization. | + +This endpoint allows you to create an Agent Pool for an organization. Only one Agent Pool may exist for an organization. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "agent-pools"`) | Agent Pool successfully created | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"agent-pools"`. | +| `data.attributes.name` | string | | The name of the agent pool, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. | +| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). | + +### Sample Payload + +```json +{ + "data": { + "type": "agent-pools", + "attributes": { + "name": "my-pool", + "organization-scoped": false + }, + "relationships": { + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/agent-pools +``` + +### Sample Response + +```json +{ + "data": { + "id": "apool-55jZekR57npjHHYQ", + "type": "agent-pools", + "attributes": { + "name": "my-pool", + "created-at": "2020-10-13T16:32:45.165Z", + "organization-scoped": false, + + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/authentication-tokens" + } + }, + "workspaces": { + "data": [] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ" + } + } +} +``` + +## Update an Agent Pool + +`PATCH /agent-pools/:id` + +| Parameter | Description | +| --------- | ---------------------------------- | +| `:id` | The ID of the Agent Pool to update | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "agent-pools"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | +| [422][] | JSON error document | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"agent-pools"`. | +| `data.attributes.name` | string | (previous value) | The name of the agent pool, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. | +| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). | + +### Sample Payload + +```json +{ + "data": { + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "organization-scoped": false + }, + "relationships": { + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + } + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd +``` + +### Sample Response + +```json +{ + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "created-at": "2020-08-05T18:10:26.964Z" + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-9EEkcEQSA3XgWyGe", + "type": "workspaces" + } + ] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i" + } + } +} +``` + +## Delete an Agent Pool + +`DELETE /agent-pools/:agent_pool_id` + +| Parameter | Description | +| ---------------- | ------------------------------------- | +| `:agent_pool_id` | The ID of the agent pool ID to delete | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd +``` + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | ------------------------------------------- | +| `workspaces` | The workspaces attached to this agent pool. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/applies.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/applies.mdx new file mode 100644 index 0000000000..a124bf588c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/applies.mdx @@ -0,0 +1,201 @@ +--- +page_title: /applies API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/applies` endpoint to read the results of + a Terraform apply and to recover any failed state uploads after applying. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[307]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Applies API reference + +An apply represents the results of applying a Terraform Run's execution plan. + +## Attributes + +### Apply States + +You'll find the apply state in `data.attributes.status`, as one of the following values. + +| State | Description | +| ------------------------- | ------------------------------------------------------------------------------ | +| `pending` | The initial status of a apply once it has been created. | +| `managed_queued`/`queued` | The apply has been queued, awaiting backend service capacity to run terraform. | +| `running` | The apply is running. | +| `errored` | The apply has errored. This is a final state. | +| `canceled` | The apply has been canceled. This is a final state. | +| `finished` | The apply has completed successfully. This is a final state. | +| `unreachable` | The apply will not run. This is a final state. | + +## Show an apply + +`GET /applies/:id` + +| Parameter | Description | +| --------- | ---------------------------- | +| `id` | The ID of the apply to show. | + +There is no endpoint to list applies. You can find the ID for an apply in the +`relationships.apply` property of a run object. + +| Status | Response | Reason | +| ------- | ----------------------------------------- | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "applies"`) | The request was successful | +| [404][] | [JSON API error object][] | Apply not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v +``` + +### Sample Response + +```json +{ + "data": { + "id": "apply-47MBvjwzBG8YKc2v", + "type": "applies", + "attributes": { + "execution-details": { + "mode": "remote", + }, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-10-17T18:58:27+00:00", + "started-at": "2018-10-17T18:58:29+00:00", + "finished-at": "2018-10-17T18:58:37+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg", + "resource-additions": 1, + "resource-changes": 0, + "resource-destructions": 0, + "resource-imports": 0 + }, + "relationships": { + "state-versions": { + "data": [ + { + "id": "sv-TpnsuD3iewwsfeRD", + "type": "state-versions" + }, + { + "id": "sv-Fu1n6a3TgJ1Typq9", + "type": "state-versions" + } + ] + } + }, + "links": { + "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v" + } + } +} +``` + +_Using HCP Terraform agents_ + +[HCP Terraform agents](/terraform/enterprise/api-docs/agents) allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. When a workspace is set to use the agent execution mode, the apply response will include additional details about the agent pool and agent used. + +```json +{ + "data": { + "id": "apply-47MBvjwzBG8YKc2v", + "type": "applies", + "attributes": { + "execution-details": { + "agent-id": "agent-S1Y7tcKxXPJDQAvq", + "agent-name": "agent_01", + "agent-pool-id": "apool-Zigq2VGreKq7nwph", + "agent-pool-name": "first-pool", + "mode": "agent", + }, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-10-17T18:58:27+00:00", + "started-at": "2018-10-17T18:58:29+00:00", + "finished-at": "2018-10-17T18:58:37+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg", + "resource-additions": 1, + "resource-changes": 0, + "resource-destructions": 0, + "resource-imports": 0 + }, + "relationships": { + "state-versions": { + "data": [ + { + "id": "sv-TpnsuD3iewwsfeRD", + "type": "state-versions" + }, + { + "id": "sv-Fu1n6a3TgJ1Typq9", + "type": "state-versions" + } + ] + } + }, + "links": { + "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v" + } + } +} +``` + +## Recover a failed state upload after applying + +`GET /applies/:id/errored-state` + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `id` | The ID of the apply to recover state for. | + +It is possible that during the course of a Run, Terraform may fail to upload a +state file. This can happen for a variety of reasons, but should be an +exceptionally rare occurrence. HCP Terraform agent versions greater than 1.12.0 +include a fallback mechanism which attempts to upload the state directly to +HCP Terraform's backend storage system in these cases. This endpoint then +makes the raw data from these failed uploads available to users who are +authorized to read the state contents. + +| Status | Response | Reason | +| ------- | -------------------------------------------- | ----------------------------------------------------------------------------------- | +| [307][] | HTTP temporary redirect to state storage URL | Errored state available and user is authorized to read it | +| [404][] | [JSON API error object][] | Apply not found, errored state not uploaded, or user unauthorized to perform action | + +When a 307 redirect is returned, the storage URL to the raw state file will be +present in the `Location` header of the response. The URL in the `Location` +header will expire after one minute. It is recommended for the API client to +follow the redirect immediately. Each successful request to the errored-state +endpoint will generate a new, unique storage URL with the same one minute +expiration window. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v/errored-state +``` + +### Sample Response + + HTTP/1.1 307 Temporary Redirect + Content-Length: 22 + Content-Type: text/plain + Location: https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg + + 307 Temporary Redirect diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/assessment-results.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/assessment-results.mdx new file mode 100644 index 0000000000..6ce07a2eda --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/assessment-results.mdx @@ -0,0 +1,129 @@ +--- +page_title: /assessment-results API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/assessment-results` endpoint to read a + health assessment's results, including details on continuous validation and + drift detection. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +# Health assessment results API reference + +An Assessment Result is the summary record of an instance of health assessment. HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Refer to [Health](/terraform/enterprise/workspaces/health) for more details. + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +## Show Assessment Result + +Any user with read access to a workspace can retrieve assessment results for the workspace. + +`GET api/v2/assessment-results/:assessment_result_id` + +| Parameter | Description | +| ----------------------- | ------------------------ | +| `:assessment_result_id` | The assessment result ID | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm +``` + +### Sample Response + +```json +{ + "id": "asmtres-UG5rE9L1373hMYMA", + "type": "assessment-results", + "data": { + "attributes": { + "drifted": true, + "succeeded": true, + "error-msg": null, + "created-at": "2022-07-02T22:29:58+00:00", + }, + "links": { + "self": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/" + "json-output": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/json-output" + "json-schema": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/json-schema" + "log-output": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/log-output" + } + } +} +``` + +## Retrieve the JSON output from the assessment execution + +The following endpoints retrieve files documenting the plan, schema, and logged runtime associated with the specified assessment result. They provide complete context for an assessment result. The responses do not adhere to JSON API spec. + +You cannot access these endpoints with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access them with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) that has admin level access to the workspace. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### JSON Plan + +The following endpoint returns the JSON plan output associated with the assessment result. + +`GET api/v2/assessment-results/:assessment_result_id/json-output` + +#### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/json-output +``` + +### JSON Schema file + +The following endpoint returns the JSON [provider schema](/terraform/cli/commands/providers/schema) associated with the assessment result. + +`GET api/v2/assessment-results/:assessment_result_id/json-schema` + +#### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/json-schema +``` + +### JSON Log Output + +The following endpoint returns Terraform JSON log output. + +`GET api/v2/assessment-results/assessment_result_id/log-output` + +#### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/log-output +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/changelog.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/changelog.mdx new file mode 100644 index 0000000000..3fec8bba90 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/changelog.mdx @@ -0,0 +1,565 @@ +--- +page_title: API Changelog for Terraform Enterprise +page_id: api-changelog +description: >- + Use this log of Terraform Enterprise API changes to track new features and + evolving functionality over time. +source: terraform-docs-common +--- + +# API Changelog + +Keep track of changes to the API for HCP Terraform and Terraform Enterprise. + +## 2025-3-10 + +- Document unique pagination metadata given in the response of [Organization Runs Index API](/terraform/enterprise/api-docs/run##list-runs-in-an-organization). + +## 2025-03-10 + +- Add new field `current_rum_count` to the [explorer API](/terraform/enterprise/api-docs/explorer) in the `workspaces` view type that lists a workspace's current resources under management. + +## 2024-11-19 + +- Clarify `tag-bindings` and `effective-tag-bindings` on [workspaces](/terraform/enterprise/api-docs/workspaces) and [projects](/terraform/enterprise/api-docs/projects) +- Adds new documentation for `PATCH`ing tag bindings on [projects](/terraform/enterprise/api-docs/projects) and [workspaces](/terraform/enterprise/api-docs/workspaces) + +## 2024-10-15 + +- Add new documentation for the ability to deprecate, and revert the deprecation of, module versions. Learn more about [Managing module versions](/terraform/enterprise/api-docs/private-registry/manage-module-versions). + +## 2024-10-14 + +- Update the [Organizations API](/terraform/enterprise/api-docs/organizations) to support the `speculative-plan-management-enabled` attribute, which controls [automatic cancellation of plan-only runs triggered by outdated commits](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management). + +## 2024-10-11 + +- Add documentation for new timeframe filter on List endpoints for [Runs](/terraform/enterprise/api-docs/run) API + +## 2024-09-02 + +- Add warning about the deprecation and future removal of the [Policy Checks](/terraform/enterprise/api-docs/policy-checks) API. + +## 2024-08-16 + +- Fixes Workspace API responses to be consistent and contain all attributes and relationships. + +## 2024-08-14 + +- Add documentation for a new API endpoint that lists an [organization's team tokens](/terraform/enterprise/api-docs/team-tokens). + +## 2024-08-01 + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. + + +- Update the [admin settings API](/terraform/enterprise/api-docs/admin/settings##update-general-settings) and [admin organizations API](/terraform/enterprise/api-docs/admin/organizations#update-an-organization) to indicate that the `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes are deprecated and will be replaced by `plan-timeout` and `apply-timeout`, respectively. + + + +## 2024-07-24 + +- Remove beta tags from documentation for audit trail tokens. + + +## 2024-07-15 + +- Update the [Team API](/terraform/enterprise/api-docs/teams) to include `allow-member-token-management`. + + + +## 2024-07-12 + +- Add beta tags to documentation for audit trail tokens. + + +## 2024-06-25 + +- Add API documentation for new [team token management setting](/terraform/enterprise/users-teams-organizations/api-tokens). +- Update API documentation for the [manage teams permission](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions). + +## 2024-05-29 + +- Add API documentation for the new [audit trails token](/terraform/enterprise/api-docs/audit-trails-tokens). + +## 2024-05-23 + +- Update the [registry modules API](/terraform/enterprise/api-docs/private-registry/modules#create-a-module-version) for publishing new versions of branch based modules. + +## 2024-05-10 + +- Add API documentation for new [manage agent pools permission](/terraform/enterprise/users-teams-organizations/permissions#manage-agent-pools). + +## 2024-04-25 + +- Project names can now be up to 40 characters. + +## 2024-04-08 + +- Add API documentation for new [team management permissions](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions). + +## 2024-04-04 + +- Add a `sort` parameter to the [Projects list API](/terraform/enterprise/api-docs/projects#query-parameters) to allow sorting projects by name. +- Add a `description` attribute to the [Projects API](/terraform/enterprise/api-docs/projects). +- Add `project-count` and `workspace-count` attributes to sample [Projects API](/terraform/enterprise/api-docs/projects) responses. + +## 2024-3-27 + +- Add `private-vcs` to [Feature Entitlements](/terraform/enterprise/api-docs#feature-entitlements). + +## 2024-3-26 + +- Add API documentation for searching [variable sets](/terraform/enterprise/api-docs/variable-sets#list-variable-sets) by name. + +## 2024-3-14 + +- Add documentation for creating runs with debugging mode enabled. + +## 2024-3-12 + +- Update OAuth Client API endpoints to create, update, and return projects associated with an oauth client. +- Add API endpoints to [Attach an OAuth Client](/terraform/enterprise/api-docs/oauth-clients#attach-an-oauth-client-to-projects) and [Detach an OAuth Client](/terraform/enterprise/api-docs/oauth-clients#detach-an-oauth-client-from-projects) from a project. +- Add `organization-scoped` attribute to the [OAuth Clients API](/terraform/enterprise/api-docs/oauth-clients). + +## 2024-2-29 + +- Update [run task stages](/terraform/enterprise/api-docs/run-tasks/run-task-stages-and-results) with new multi-stage payload format. +- Update [run tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks) with global run tasks request/response payloads. + +## 2024-2-27 + +- Add `private-policy-agents` to [Feature Entitlements](/terraform/enterprise/api-docs#feature-entitlements). + +## 2024-2-20 + +- Add documentation for configuring organization and workspace data retention policies through the API and on the different [types of data retention policies](/terraform/enterprise/api-docs/data-retention-policies). + + +## 2024-2-8 + +- Add [Explorer API documentation](/terraform/enterprise/api-docs/explorer) + + +## 2024-1-30 + +- Update the [Audit trails](/terraform/enterprise/api-docs/audit-trails) documentation to expand on the payloads for each event. + +## 2024-1-24 + +- Introduce configurable data retention policies at the site-wide level and extend data retention policies at the organization and workspace levels. +- Added and/or updated data retention policy documentation to the following topics: + - [Admin Settings Documentation](/terraform/enterprise/application-administration/general#data-retention-policies) + - [Admin API Documentation](/terraform/enterprise/api-docs/admin/settings#data-retention-policies) + - [Organization Documentation](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies) + - [Workspace Documentation](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) + +## 2024-1-4 + +- Update the [Organizations API](/terraform/enterprise/api-docs/organizations) to support the `aggregated-commit-status-enabled` attribute, which controls whether [Aggregated Status Checks](/terraform/enterprise/users-teams-organizations/organizations/vcs-status-checks) are enabled. + +## 2023-11-17 + +- Added the [`opa-versions` endpoint](/terraform/enterprise/api-docs/admin/opa-versions) to allow administrators to manage available Open Policy Agent (OPA) versions. +- Added the [`sentinel-versions` endpoint](/terraform/enterprise/api-docs/admin/sentinel-versions) to allow administrators to manage available Sentinel versions. +- Add `authenticated-resource` relationship to the [`account` API](/terraform/enterprise/api-docs/account). + +## 2023-11-15 + +- Introduce configurable data retention policies at the [organization](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies) and [workspace](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) levels. +- Added data retention policy documentation to the following topics: + - [`state-versions` API documentation](/terraform/enterprise/api-docs/state-versions) + - [`configuration-versions` API documentation](/terraform/enterprise/api-docs/configuration-versions) + - [Organizations documentation](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) + - [Workspaces documentation](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) + +## 2023-11-07 + +- Add `auto_destroy_activity_duration` to the [Workspaces API](/terraform/enterprise/api-docs/workspaces), which allows Terraform Cloud to schedule auto-destroy runs [based on workspace inactivity](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). + +## 2023-10-31 + +- Update the [Workspaces API](/terraform/enterprise/api-docs/workspaces) to support the `auto-apply-run-trigger` attribute, which controls if run trigger runs are auto-applied. + +## 2023-10-30 + +- Add `priority` attribute to the [Variable Sets API](/terraform/enterprise/api-docs/variable-sets). + +## 2023-10-04 + +- Updates to [run task integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) + - Fix invalid JSON in the example payload. + - Clarify the expected JSON:API payload fields. +- Add `policy-tool-version` attribute to [Policy Set Outcomes](/terraform/enterprise/api-docs/policy-evaluations#list-policy-outcomes). + +## 2023-10-03 + +- Update [Policy Sets API](/terraform/enterprise/api-docs/policy-sets) to include `agent-enabled` and `policy-tool-version`. +- Update [Policy Evaluations API](/terraform/enterprise/api-docs/policy-evaluations) to include `policy-tool-version`. + +## 2023-09-29 + +- Add support for [streamlined run task reviews](/terraform/enterprise/integrations/run-tasks), enabling run task integrations to return high fidelity results. + - Update the [Terraform cloud run task API](/terraform/enterprise/api-docs/run-tasks/run-tasks) to enable streamlined run task reviews. + - The [run task integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) now guides integrations through sending rich results. + - Updated the run task payload [JSON Schema](https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-result.json). + +## 2023-09-25 + +- Add `intermediate` boolean attribute to the [State Versions API](/terraform/enterprise/api-docs/state-versions). + +## 2023-09-19 + +- Add [failed state upload recovery](/terraform/enterprise/api-docs/applies#recover-a-failed-state-upload-after-applying) endpoint. + +## 2023-09-15 + +- Add `auto-destroy-at` attribute to the [Workspaces API](/terraform/enterprise/api-docs/workspaces). +- Update the [Notification Configurations API](/terraform/enterprise/api-docs/notification-configurations) to include [automatic destroy run](/terraform/enterprise/api-docs/notification-configurations#automatic-destroy-runs) details. + +## 2023-09-08 + +- Update the [Organizations API](/terraform/enterprise/api-docs/organizations) to include `default-execution-mode` and `default-agent-pool`. +- Update the [Workspaces API](/terraform/enterprise/api-docs/workspaces) to add a `setting-overwrites` object to allow you to overwrite `default-execution-mode` and `default-agent-pool`. + +## 2023-09-06 + +- Update Policy Sets API endpoints to create, update, and return excluded workspaces associated with a policy set. +- Add API endpoints to [Attach a Policy Set](/terraform/enterprise/api-docs/policy-sets#attach-a-policy-set-to-exclusions) and [Detach a Policy Set](/terraform/enterprise/api-docs/policy-sets#detach-a-policy-set-to-exclusions) from excluded workspaces. + +## 2023-08-21 + +- Add `save-plan` attribute, `planned_and_saved` status, and `save_plan` operation type to [Runs endpoints](/terraform/enterprise/api-docs/run). + +## 2023-08-10 + +- Add `provisional` to `configuration-versions` endpoint. + +## 2023-07-26 + +- Add support for a `custom` option to the `team_project` access level along with various customizable permissions. The `project-access` permissions apply to the project itself, and `workspace-access` permissions apply to all workspaces within the project. For more information, see [Project Team Access](/terraform/enterprise/api-docs/project-team-access). + +## 2023-06-09 + +- Introduce support for [`import` blocks](/terraform/language/import/generating-configuration). + - [Runs](/terraform/enterprise/api-docs/run#create-a-run) have a new `allow-config-generation` option. + - [Plans](/terraform/enterprise/api-docs/plans#show-a-plan) have new `resource-imports` and `generated-configuration` properties. + - [Applies](/terraform/enterprise/api-docs/applies#show-an-apply) have a new `resource-imports` property. +- The workspaces associated with a policy set can now be updated using the [Policy Sets PATCH endpoint](/terraform/enterprise/api-docs/policy-sets#update-a-policy-set) +- Update the [Workspaces](/terraform/enterprise/api-docs/workspaces) API endpoints to include the associated [project](/terraform/enterprise/api-docs/projects). + +## 2023-05-25 + +- Terraform Cloud sets the `configuration_version_download_url`, `configuration_version_id`, and `workspace_working_directory` properties for all stages of the [Run Task Request](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration#request-body). +- Add the new `enforcement-level` property in the request and response of [Policies endpoints](/terraform/enterprise/api-docs/policies). +- Deprecate the old `enforce` property in the request and response of [Policies endpoints](/terraform/enterprise/api-docs/policies). +- Add new properties to limit run tasks and policies for the Terraform Cloud free tier. We updated the [entitlement set](/terraform/enterprise/api-docs/organizations#show-the-entitlement-set), [feature set](/terraform/enterprise/api-docs/feature-sets#sample-response), and [subscription](/terraform/enterprise/api-docs/subscriptions#sample-response) endpoints with the following properties: + - `run-task-limit` + - `run-task-workspace-limit` + - `run-task-mandatory-enforcement-limit` + - `policy-set-limit` + - `policy-limit` + - `policy-mandatory-enforcement-limit` + - `versioned-policy-set-limit` + +## 2023-04-25 + +- Add the `version-id` property to the response for the Create, List, and Update [Workspace Variables endpoints](/terraform/enterprise/api-docs/workspaces-variables). + +## 2023-03-30 + +- Add the `sort` query parameter to the Workspaces API's [list workspaces endpoint](/terraform/enterprise/api-docs/workspaces#list-workspaces). + +## 2023-03-24 + +- Update the [Variable Sets](/terraform/enterprise/api-docs/variable-sets) API endpoints to include assigning variable sets to projects. + +## 2023-03-20 + +- Add a names filter to the [Projects list API](/terraform/enterprise/api-docs/projects#query-parameters) to allow fetching a list of projects by name. + +## 2023-03-13 + +- Update [Project Team Access API](/terraform/enterprise/api-docs/project-team-access) to include additional Project roles. +- Update [Permissions](/terraform/enterprise/users-teams-organizations/permissions) to reflect the decoupling of projects and workspaces in the Organization Permissions UI. + +## 2023-03-08 + +- Introduced the [GitHub App Installation APIs](/terraform/enterprise/api-docs/github-app-installations). +- Updated [Workspaces API](/terraform/enterprise/api-docs/workspaces) to accept `vcs-repo.github-app-installation-id` to connect a workspace to a GitHub App Installation. +- Updated [Registry Module API](/terraform/enterprise/api-docs/private-registry/modules) to accept `vcs-repo.github-app-installation-id` to connect to a GitHub App Installation. +- Updated [Policy Sets API](/terraform/enterprise/api-docs/policy-sets) to accept `vcs-repo.github-app-installation-id` to connect to a GitHub App Installation. + +## 2023-02-16 + +- Add `manage-membership` to the organization access settings of the [Team API](/terraform/enterprise/api-docs/teams). + +## 2023-02-03 + +- Updated the [List Runs API](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace) to note that the filter query parameters accept comma-separated lists. + +## 2023-01-18 + +- Updated the [Team API](/terraform/enterprise/api-docs/teams) to include the `read-workspaces` and `read-projects` permissions which grants teams view access to workspaces and projects. + +## 2023-01-17 + +- Add [Projects API](/terraform/enterprise/api-docs/projects) for creating, updating and deleting projects. +- Add [Project Team Access API](/terraform/enterprise/api-docs/project-team-access) for managing access for teams to individual projects. +- Update [Workspaces API](/terraform/enterprise/api-docs/workspaces) to include examples of creating a workspace in a project and moving a workspace between projects. +- Update [List Teams API](/terraform/enterprise/api-docs/teams#query-parameters) to accept a search parameter `q`, so that teams can be searched by name. + +## 2023-01-12 + +- Added new rollback to previous state endpoint to [State Versions API](/terraform/enterprise/api-docs/state-versions) + +## 2022-12-22 + +- Updated [Safe Delete a workspace](/terraform/enterprise/api-docs/workspaces#safe-delete-a-workspace) to fix HTTP verb as `POST`. + +## 2022-11-18 + +- Update [Policies API](/terraform/enterprise/api-docs/policies) to fix policy enforcement level defaults. Enforcement level is a required field, so no defaults are available. + +## 2022-11-03 + +- Update [Policy Checks](/terraform/enterprise/api-docs/policy-checks) to fix policy set outcome return data type. + +### 2022-10-17 + +- Updated the [Organizations API](/terraform/enterprise/api-docs/organizations) with the `allow-force-delete-workspaces`, which controls whether workspace administrators can delete workspaces with resources under management. +- Updated the [Workspaces API](/terraform/enterprise/api-docs/workspaces) with a safe delete endpoint that guards against deleting workspaces that are managing resources. + +### 2022-10-12 + +- Update [Policy Checks](/terraform/enterprise/api-docs/policy-checks) with result counts and support for filtering policy set outcomes. +- Update [Team Membership API](/terraform/enterprise/api-docs/team-members) to include adding and removing users from teams using organization membership ID. + + + +### 2022-10-06 + +- Updated the [Policies API](/terraform/enterprise/api-docs/policies) with support for Open Policy Agent (OPA) policies. +- Update [Policy Sets](/terraform/enterprise/api-docs/policy-sets) with support for OPA policy sets. +- Updated [Policy Checks](/terraform/enterprise/api-docs/policy-checks) to add support for listing policy evaluations and policy set outcomes. +- Update [Run Tasks Stage](/terraform/enterprise/api-docs/run-tasks/run-task-stages-and-results) to include the new `policy_evaluations` attribute in the output. + + +### 2022-09-21 + +- Update [State Versions](/terraform/enterprise/api-docs/state-versions#create) with optional `json-state-outputs` and `json-state` attributes, which are base-64 encoded external JSON representations of the terraform state. The read-only `hosted-json-state-download-url` attribute links to this version of the state file when available. +- Update [State Version Outputs](/terraform/enterprise/api-docs/state-version-outputs) with a `detailed-type` attribute, which refines the output with the precise Terraform type. + +### 2022-07-26 + +- Updated the [Run status list](/terraform/enterprise/api-docs/run#run-states) with `fetching`, `queuing`, `pre_plan_running` and `pre_plan_completed` +- Update [Run Tasks](/terraform/enterprise/api-docs/run-tasks.mdx) to include the new `stages` attribute when attaching or updating workspace tasks. +- Updated [Run Tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) to specify the different request payloads for different stages. + +### 2022-06-23 + + + +- Added the [Assessments](/terraform/enterprise/api-docs/assessments). + +- Updated [Workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) and + [Notification Configurations](/terraform/enterprise/api-docs/notification-configurations#notification-triggers) to account for assessments. + + +- Added new query parameter(s) to [List Runs endpoint](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace). + +### 2022-06-21 + +- Updated [Admin Organizations](/terraform/enterprise/api-docs/admin/organizations) endpoints with new `workspace-limit` setting. This is available in Terraform Enterprise v202207-1 and later. +- Updated [List Agent Pools](/terraform/enterprise/api-docs/agents#list-agent-pools) to accept a filter parameter `filter[allowed_workspaces][name]` so that agent pools can be filtered by name of an associated workspace. The given workspace must be allowed to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). +- Added new `organization-scoped` attribute and `allowed-workspaces` relationship to the request/response body of the below endpoints. This is available in Terraform Enterprise v202207-1 and later. + - [Show an Agent Pool](/terraform/enterprise/api-docs/agents#show-an-agent-pool) + - [Create an Agent Pool](/terraform/enterprise/api-docs/agents#create-an-agent-pool) + - [Update an Agent Pool](/terraform/enterprise/api-docs/agents#update-an-agent-pool) + +### 2022-06-17 + +- Updated [Creating a Run Task](/terraform/enterprise/workspaces/settings/run-tasks#creating-a-run-task) section to include the new description information for the run task to be configured. +- Update [Run Tasks](/terraform/enterprise/api-docs/run-tasks.mdx) to include the new description attribute. + +### 2022-06-09 + +- Updated [List Agent Pools](/terraform/enterprise/api-docs/agents#list-agent-pools) to accept a search parameter `q`, so that agent pools can be searched by `name`. This is available in Terraform Enterprise v202207-1 and later. +- Fixed [List Workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces) to add missing `search[tags]` query parameter. +- Updated [List Workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces) to add new `search[exclude_tags]` query parameter. This is available in Terraform Enterprise v202207-1 and later. + +### 2022-05-11 + +- Updated Run Tasks permission to the following endpoints: + - [Organizations](/terraform/enterprise/api-docs/organizations#list-organizations). + - [Team Access](/terraform/enterprise/api-docs/team-access#list-team-access-to-a-workspace). + - [Teams](/terraform/enterprise/api-docs/teams#list-teams). + +### 2022-05-04 + +- Updated [Feature Sets](/terraform/enterprise/api-docs/feature-sets#list-feature-sets) to add new `run-tasks` attribute. + +### 2022-05-03 + +- Added Run Tasks permission to the following endpoints: + - [Organizations](/terraform/enterprise/api-docs/organizations#list-organizations) + - [Workspaces](/terraform/enterprise/api-docs/workspaces#show-workspace) + +### 2022-04-29 + +- Updated [Run Tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) to specify the allowed `status` attribute values. +- Updated [Organization Memberships](/terraform/enterprise/api-docs/organization-memberships#query-parameters) to add new `filter[email]` query parameter. +- Updated [Teams](/terraform/enterprise/api-docs/teams#query-parameters) to add new `filter[names]` query parameter. + +### 2022-04-04 + +- Added the [Run Tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) endpoint. + +### 2022-03-14 + +- Added the [Download Configuration Files](/terraform/enterprise/api-docs/configuration-versions#download-configuration-files) endpoints. + +### 2022-03-11 + +- Introduced [Archiving Configuration Versions](/terraform/enterprise/workspaces/configurations#archiving-configuration-versions). + - Updated [Configuration Versions](/terraform/enterprise/api-docs/configuration-versions#attributes) to add new `fetching` and `archived` states. + - Updated [Runs](/terraform/enterprise/api-docs/run#attributes) to add new `fetching` state. + - Added the [Archive a Configuration Version](/terraform/enterprise/api-docs/configuration-versions#archive-a-configuration-version) endpoint. + +### 2022-02-25 + +- Updated [Workspace Run Tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks#show-a-run-task) to add new `enabled`attribute. + +### 2022-02-28 + +- Introduced the [Registry Providers](/terraform/enterprise/api-docs/private-registry/providers) endpoints to manage private providers for a private registry. + +### 2021-12-09 + +- Added `variables` field for POST /runs and the run resource, enabling run-specific variable values. + +### 2021-12-03 + +- OAuth API updated to handle `secret` and `rsa_public_key` fields for POST/PUT. + +### 2021-11-17 + +- Added pagination support to the following endpoints: + - [Feature Sets](/terraform/enterprise/api-docs/feature-sets#list-feature-sets) - `GET /feature-sets` + - [Notification Configurations](/terraform/enterprise/api-docs/notification-configurations#list-notification-configurations) - `GET /workspaces/:workspace_id/notification-configurations` + - [Oauth Clients](/terraform/enterprise/api-docs/oauth-clients#list-oauth-clients) - `GET /organizations/:organization_name/oauth-clients` + - [Oauth Tokens](/terraform/enterprise/api-docs/oauth-tokens#list-oauth-tokens) - `GET /oauth-clients/:oauth_client_id/oauth-tokens` + - [Organization Feature Sets](/terraform/enterprise/api-docs/feature-sets#list-feature-sets-for-organization) - `GET /organizations/:organization_name/feature-sets` + - [Organizations](/terraform/enterprise/api-docs/organizations#list-organizations) - `GET /organizations` + - [Policy Checks](/terraform/enterprise/api-docs/policy-checks#list-policy-checks) - `GET /runs/:run_id/policy-checks` + - [Policy Set Parameters](/terraform/enterprise/api-docs/policy-set-params#list-parameters) - `GET /policy-sets/:policy_set_id/parameters` + - [SSH Keys](/terraform/enterprise/api-docs/ssh-keys#list-ssh-keys) - `GET /organizations/:organization_name/ssh-keys` + - [User Tokens](/terraform/enterprise/api-docs/user-tokens#list-user-tokens) - `GET /users/:user_id/authentication-tokens` + +### 2021-11-11 + +- Introduced the [Variable Sets](/terraform/enterprise/api-docs/variable-sets) endpoints for viewing and administering Variable Sets + +### 2021-11-18 + +- Introduced the [Registry Providers](/terraform/enterprise/api-docs/private-registry/providers) endpoint to manage public providers for a + private registry. These endpoints will be available in the following Terraform Enterprise Release: `v202112-1` + +### 2021-09-12 + +- Added [Run Tasks Stages and Results](/terraform/enterprise/api-docs/run-tasks/run-task-stages-and-results) endpoint. + +### 2021-08-18 + +- Introduced the [State Version Outputs](/terraform/enterprise/api-docs/state-versions) endpoint to retrieve the Outputs for a + given State Version + +### 2021-08-11 + +- **BREAKING CHANGE:** Security fix to [Configuration versions](/terraform/enterprise/api-docs/configuration-versions): upload-url attribute for [uploading configuration files](/terraform/enterprise/api-docs/configuration-versions#upload-configuration-files) is now only available on the create response. + +### 2021-07-30 + +- Introduced Workspace Tagging + - Updated [Workspaces](/terraform/enterprise/api-docs/workspaces): + - added `tag-names` attribute. + - added `POST /workspaces/:workspace_id/relationships/tags` + - added `DELETE /workspaces/:workspace_id/relationships/tags` + - Added [Organization Tags](/terraform/enterprise/api-docs/organization-tags). + - Added `tags` attribute to [`tfrun`](/terraform/enterprise/policy-enforcement/sentinel/import/tfrun) + +### 2021-07-19 + +- [Notification configurations](/terraform/enterprise/api-docs/notification-configurations): Gave organization tokens permission to create and manage notification configurations. + +### 2021-07-09 + +- [State versions](/terraform/enterprise/api-docs/state-versions): Fixed the ID format for the workspace relationship of a state version. Previously, the reported ID was unusable due to a bug. +- [Workspaces](/terraform/enterprise/api-docs/workspaces): Added `locked_by` as an includable related resource. +- Added [Run Tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks) API endpoint. + +### 2021-06-8 + +- Updated [Registry Module APIs](/terraform/enterprise/api-docs/private-registry/modules). + - added `registry_name` scoped APIs. + - added `organization_name` scoped APIs. + - added [Module List API](/terraform/enterprise/api-docs/private-registry/modules#list-registry-modules-for-an-organization). + - updated [Module Delete APIs](/terraform/enterprise/api-docs/private-registry/modules#delete-a-module) (see deprecation note below). + - **CLOUD**: added public registry module related APIs. +- **DEPRECATION**: The following [Registry Module APIs](/terraform/enterprise/api-docs/private-registry/modules) have been replaced with newer apis and will be removed in the future. + - The following endpoints to delete modules are replaced with [Module Delete APIs](/terraform/enterprise/api-docs/private-registry/modules#delete-a-module) + - `POST /registry-modules/actions/delete/:organization_name/:name/:provider/:version` replaced with `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/:version` + - `POST /registry-modules/actions/delete/:organization_name/:name/:provider` replaced with `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider` + - `POST /registry-modules/actions/delete/:organization_name/:name` replaced with `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name` + - `POST /registry-modules` replaced with [`POST /organizations/:organization_name/registry-modules/vcs`](/terraform/enterprise/api-docs/private-registry/modules#publish-a-private-module-from-a-vcs) + - `POST /registry-modules/:organization_name/:name/:provider/versions` replaced with [`POST /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/versions`](/terraform/enterprise/api-docs/private-registry/modules#create-a-module-version) + - `GET /registry-modules/show/:organization_name/:name/:provider` replaced with [`GET /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider`](/terraform/enterprise/api-docs/private-registry/modules#get-a-module) + +### 2021-05-27 + +- **CLOUD**: [Agents](/terraform/enterprise/api-docs/agents): added [delete endpoint](/terraform/enterprise/api-docs/agents#delete-an-agent). + +### 2021-05-19 + +- [Runs](/terraform/enterprise/api-docs/run): added `refresh`, `refresh-only`, and `replace-addrs` attributes. + +### 2021-04-16 + +- Introduced [Controlled Remote State Access](https://www.hashicorp.com/blog/announcing-controlled-remote-state-access-for-terraform-cloud-and-enterprise). + - [Admin Settings](/terraform/enterprise/api-docs/admin/settings): added `default-remote-state-access` attribute. + - [Workspaces](/terraform/enterprise/api-docs/workspaces): + - added `global-remote-state` attribute. + - added [Remote State Consumers](/terraform/enterprise/api-docs/workspaces#get-remote-state-consumers) relationship. + +### 2021-04-13 + +- [Teams](/terraform/enterprise/api-docs/teams): added `manage-policy-overrides` property to the `organization-access` attribute. + +### 2021-03-23 + +- **ENTERPRISE**: `v202103-1` Introduced [Share Modules Across Organizations with Terraform Enterprise](https://www.hashicorp.com/blog/share-modules-across-organizations-terraform-enterprise). + - [Admin Organizations](/terraform/enterprise/api-docs/admin/organizations): + - added new query parameters to [List all Organizations endpoint](/terraform/enterprise/api-docs/admin/organizations#query-parameters) + - added module-consumers link in `relationships` response + - added [update module consumers endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization-39-s-module-consumers) + - added [list module consumers endpoint](/terraform/enterprise/api-docs/admin/organizations#list-module-consumers-for-an-organization) + - [Organizations](/terraform/enterprise/api-docs/organizations): added [Module Producers](/terraform/enterprise/api-docs/organizations#show-module-producers) + - **DEPRECATION**: [Admin Module Sharing](/terraform/enterprise/api-docs/admin/module-sharing): is replaced with a new JSON::Api compliant [endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization-39-s-module-consumers) + +### 2021-03-18 + +- **CLOUD**: Introduced [New Workspace Overview for Terraform Cloud](https://www.hashicorp.com/blog/new-workspace-overview-for-terraform-cloud). + - [Workspaces](/terraform/enterprise/api-docs/workspaces): + - added `resource-count` and `updated-at` attributes. + - added [performance attributes](/terraform/enterprise/api-docs/workspaces#workspace-performance-attributes) (`apply-duration-average`, `plan-duration-average`, `policy-check-failures`, `run-failures`, `workspaces-kpis-run-count`). + - added `readme` and `outputs` [related resources](/terraform/enterprise/api-docs/workspaces#available-related-resources). + - [Team Access](/terraform/enterprise/api-docs/team-access): updated to support pagination. + +### 2021-03-11 + +- Added [VCS Events](/terraform/enterprise/api-docs/vcs-events), limited to GitLab.com connections. + +### 2021-03-08 + +- [Workspaces](/terraform/enterprise/api-docs/workspaces): added `current_configuration_version` and `current_configuration_version.ingress_attributes` as includable related resources. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/comments.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/comments.mdx new file mode 100644 index 0000000000..2e96414328 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/comments.mdx @@ -0,0 +1,227 @@ +--- +page_title: /comments API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/comments` endpoint to create and read + comments on Terraform runs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[307]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Comments API reference + +Comments allow users to leave feedback or record decisions about a run. + +## List Comments for a Run + +`GET /runs/:id/comments` + +| Parameter | Description | +| --------- | ------------------ | +| `id` | The ID of the run. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/runs/run-KTuq99JSzgmDSvYj/comments +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsc-JdFX3u8o114F4CWf", + "type": "comments", + "attributes": { + "body": "A comment body" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-fo1YXZ8W5bp5GBKM", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-fo1YXZ8W5bp5GBKM" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-JdFX3u8o114F4CWf" + } + }, + { + "id": "wsc-QdhSPFTNoCTpfafp", + "type": "comments", + "attributes": { + "body": "Another comment body" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-fo1YXZ8W5bp5GBKM", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-fo1YXZ8W5bp5GBKM" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-QdhSPFTNoCTpfafp" + } + } + ] +} +``` + +## Show a Comment + +`GET /comments/:id` + +| Parameter | Description | +| --------- | ---------------------- | +| `id` | The ID of the comment. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/comments/wsc-gTFq83JSzjmAvYj +``` + +### Sample Response + +```json +{ + "data": { + "id": "wsc-gTFq83JSzjmAvYj", + "type": "comments", + "attributes": { + "body": "Another comment" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-8RB5ZaFrDanG2hGY", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-8RB5ZaFrDanG2hGY" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-gTFq83JSzjmAvYj" + } + } +} +``` + +## Create Comment + +`POST /runs/:id/comments` + +| Parameter | Description | +| --------- | ------------------ | +| `id` | The ID of the run. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as the request payload. + +| Key Path | Type | Default | Description | +| ---------------------- | ------ | ------- | ------------------------ | +| `data.type` | string | | Must be `"comments"`. | +| `data.attributes.body` | string | | The body of the comment. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "body": "A comment about the run", + }, + "type": "comments" + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/runs/run-KTuq99JSzgmDSvYj/comments +``` + +### Sample Response + +```json +{ + "data": { + "id": "wsc-oRiShushpgLU4JD2", + "type": "comments", + "attributes": { + "body": "A comment about the run" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-E3xsBX11F1fbm2zV", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-E3xsBX11F1fbm2zV" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-oRiShushpgLU4JD2" + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/configuration-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/configuration-versions.mdx new file mode 100644 index 0000000000..8b5f077525 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/configuration-versions.mdx @@ -0,0 +1,561 @@ +--- +page_title: /configuration-versions API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/configuration-versions` endpoint to list, + show, and create a configuration version and its files within a workspace. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[302]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Configuration versions API reference + +-> **Note:** Before working with the runs or configuration versions APIs, read the [API-driven run workflow](/terraform/enterprise/run/api) page, which includes both a full overview of this workflow and a walkthrough of a simple implementation of it. + +A configuration version (`configuration-version`) is a resource used to reference the uploaded configuration files. It is associated with the run to use the uploaded configuration files for performing the plan and apply. + +You need read runs permission to list and view configuration versions for a workspace, and you need queue plans permission to create new configuration versions. Refer to the [permissions](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) documentation for more details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Attributes + +### Configuration Version States + +The configuration version state is found in `data.attributes.status`, and you can reference the following list of possible states. + +A configuration version created through the API or CLI can only be used in runs if it is in an `uploaded` state. A configuration version created through a linked VCS repository may also be used in runs if it is in an `archived` state. + +| State | Description | | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | +| `pending` | The initial status of a configuration version after it has been created. Pending configuration versions cannot be used to create new runs. | | +| `fetching` | For configuration versions created from a commit to a connected VCS repository, HCP Terraform is currently fetching the associated files from VCS. | | +| `uploaded` | The configuration version is fully processed and can be used in runs. | | +| `archived` | All immediate runs are complete and HCP Terraform has discarded the files associated with this configuration version. If the configuration version was created through a connected VCS repository, it can still be used in new runs. In those cases, HCP Terraform will re-fetch the files from VCS. | | +| `errored` | HCP Terraform could not process this configuration version, and it cannot be used to create new runs. You can try again by pushing a new commit to your linked VCS repository or creating a new configuration version with the API or CLI. | | +| `backing_data_soft_deleted` | Indicates that the configuration version's backing data is marked for garbage collection. If no action is taken, the backing data associated with this configuration version is permanently deleted after a set number of days. You can restore the backing data associated with the configuration version before it is permanently deleted. | | +| `backing_data_permanently_deleted` | The configuration version's backing data has been permanently deleted and can no longer be restored. | | + +## List Configuration Versions + +`GET /workspaces/:workspace_id/configuration-versions` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list configurations from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 configuration versions per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/workspaces/ws-2Qhk7LHgbMrm3grF/configuration-versions +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "cv-ntv3HbhJqvFzamy7", + "type": "configuration-versions", + "attributes": { + "error": null, + "error-message": null, + "source": "gitlab", + "speculative":false, + "status": "uploaded", + "status-timestamps": {}, + "provisional": false + }, + "relationships": { + "ingress-attributes": { + "data": { + "id": "ia-i4MrTxmQXYxH2nYD", + "type": "ingress-attributes" + }, + "links": { + "related": + "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes" + } + } + }, + "links": { + "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7", + "download": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download" + } + } + ] +} +``` + +## Show a Configuration Version + +`GET /configuration-versions/:configuration-id` + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:configuration-id` | The id of the configuration to show. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7 +``` + +### Sample Response + +```json +{ + "data": { + "id": "cv-ntv3HbhJqvFzamy7", + "type": "configuration-versions", + "attributes": { + "error": null, + "error-message": null, + "source": "gitlab", + "speculative":false, + "status": "uploaded", + "status-timestamps": {}, + "provisional": false + }, + "relationships": { + "ingress-attributes": { + "data": { + "id": "ia-i4MrTxmQXYxH2nYD", + "type": "ingress-attributes" + }, + "links": { + "related": + "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes" + } + } + }, + "links": { + "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7", + "download": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download" + } + } +} +``` + +## Show a Configuration Version's Commit Information + +An ingress attributes resource (`ingress-attributes`) is used to reference commit information for configuration versions created in a workspace with a VCS repository. + +`GET /configuration-versions/:configuration-id/ingress-attributes` + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:configuration-id` | The id of the configuration to show. | + +Ingress attributes can also be fetched as part of a query to a particular configuration version via `include`: + +`GET /configuration-versions/:configuration-id?include=ingress-attributes` + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:configuration-id` | The id of the configuration to show. | + + + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/configuration-versions/cv-TrHjxIzad9Ae9i8x/ingress-attributes +``` + +### Sample Response + +```json +{ + "data": { + "id": "ia-zqHjxJzaB9Ae6i9t", + "type": "ingress-attributes", + "attributes": { + "branch": "add-cool-stuff", + "clone-url": "https://github.com/hashicorp/foobar.git", + "commit-message": "Adding really cool infrastructure", + "commit-sha": "1e1c1018d1bbc0b8517d072718e0d87c1a0eda95", + "commit-url": "https://github.com/hashicorp/foobar/commit/1e1c1018d1bbc0b8517d072718e0d87c1a0eda95", + "compare-url": "https://github.com/hashicorp/foobar/pull/163", + "identifier": "hashicorp/foobar", + "is-pull-request": true, + "on-default-branch": false, + "pull-request-number": 163, + "pull-request-url": "https://github.com/hashicorp/foobar/pull/163", + "pull-request-title": "Adding really cool infrastructure", + "pull-request-body": "These are changes to add really cool stuff. We should absolutely merge this.", + "tag": null, + "sender-username": "chrisarcand", + "sender-avatar-url": "https://avatars.githubusercontent.com/u/2430490?v=4", + "sender-html-url": "https://github.com/chrisarcand" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-PQk2Z3dfXAax18P6s", + "type": "users" + }, + "links": { + "related": "/api/v2/ingress-attributes/ia-zqHjxJzaB9Ae6i9t/created-by" + } + } + }, + "links": { + "self": "/api/v2/ingress-attributes/ia-zqHjxJzaB9Ae6i9t" + } + } +} +``` + +## Create a Configuration Version + +`POST /workspaces/:workspace_id/configuration-versions` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to create the new configuration version in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.auto-queue-runs` | boolean | true | When true, runs are queued automatically when the configuration version is uploaded. | +| `data.attributes.speculative` | boolean | false | When true, this configuration version may only be used to create runs which are speculative, that is, can neither be confirmed nor applied. | +| `data.attributes.provisional` | boolean | false | When true, this configuration version does not immediately become the workspace current configuration version. If the associated run is applied, it then becomes the current configuration version unless a newer one exists. | + +### Sample Payload + +```json +{ + "data": { + "type": "configuration-versions", + "attributes": { + "auto-queue-runs": true + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-2Qhk7LHgbMrm3grF/configuration-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "cv-UYwHEakurukz85nW", + "type": "configuration-versions", + "attributes": { + "auto-queue-runs": true, + "error": null, + "error-message": null, + "source": "tfe-api", + "speculative":false, + "status": "pending", + "status-timestamps": {}, + "upload-url": + "https://archivist.terraform.io/v1/object/9224c6b3-2e14-4cd7-adff-ed484d7294c2", + "provisional": false + }, + "relationships": { + "ingress-attributes": { + "data": null, + "links": { + "related": + "/api/v2/configuration-versions/cv-UYwHEakurukz85nW/ingress-attributes" + } + } + }, + "links": { "self": "/api/v2/configuration-versions/cv-UYwHEakurukz85nW" } + } +} +``` + +### Configuration Files Upload URL + +Once a configuration version is created, use the `upload-url` attribute to [upload configuration files](#upload-configuration-files) associated with that version. The `upload-url` attribute is only provided in the response when creating configuration versions. + +## Upload Configuration Files + +-> **Note**: If `auto-queue-runs` was either not provided or set to `true` during creation of the configuration version, a run using this configuration version will be automatically queued on the workspace. If `auto-queue-runs` was set to `false` explicitly, then it is necessary to [create a run on the workspace](/terraform/enterprise/api-docs/run#create-a-run) manually after the configuration version is uploaded. + +`PUT https://archivist.terraform.io/v1/object/` + +**The URL is provided in the `upload-url` attribute when creating a `configuration-versions` resource. After creation, the URL is hidden on the resource and no longer available.** + +### Sample Request + +**@filename is the name of configuration file you wish to upload.** + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @filename \ + https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da +``` + +## Archive a Configuration Version + +`POST /configuration-versions/:configuration_version_id/actions/archive` + +| Parameter | Description | +| -------------------------- | ----------------------------------------------- | +| `configuration_version_id` | The ID of the configuration version to archive. | + +This endpoint notifies HCP Terraform to discard the uploaded `.tar.gz` file associated with this configuration version. This endpoint can only archive configuration versions that were created with the API or CLI, are in an `uploaded` [state](#configuration-version-states), have no runs in progress, and are not the current configuration version for any workspace. Otherwise, calling this endpoint will result in an error. + +HCP Terraform automatically archives configuration versions created through VCS when associated runs are complete and then re-fetches the files for subsequent runs. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [202][] | none | Successfully initiated the archive process. | +| [409][] | [JSON API error object][] | Configuration version was in a non-archivable state or the configuration version was created with VCS and cannot be archived through the API. | +| [404][] | [JSON API error object][] | Configuration version was not found or user not authorized. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/archive +``` + +## Download Configuration Files + +`GET /configuration-versions/:configuration_version_id/download` + +| Parameter | Description | +| -------------------------- | ------------------------------------------------ | +| `configuration_version_id` | The ID of the configuration version to download. | + +`GET /runs/:run_id/configuration-version/download` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------- | +| `run_id` | The ID of the run whose configuration version should be downloaded. | + +These endpoints generate a temporary URL to the location of the configuration version in a `.tar.gz` archive, and then redirect to that link. If using a client that can follow redirects, you can use these endpoints to save the `.tar.gz` archive locally without needing to save the temporary URL. These endpoints will return an error if attempting to download a configuration version that is not in an `uploaded` [state](#configuration-version-states). + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| [302][] | HTTP Redirect | Configuration version found and temporary download URL generated | +| [404][] | [JSON API error object][] | Configuration version not found, or specified configuration version is not uploaded, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --location \ + https://app.terraform.io/api/v2/configuration-versions/cv-C6Py6WQ1cUXQX2x2/download \ + > export.tar.gz +``` + +## Mark a Configuration Version for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/configuration-versions/:configuration-id/actions/soft_delete_backing_data` + +| Parameter | Description | +| ------------------- | --------------------------------------------------- | +| `:configuration-id` | The ID of the configuration version to soft delete. | + +This endpoint directs Terraform Enterprise to _soft delete_ the backing files associated with the configuration version. Soft deletion refers to marking the configuration version for garbage collection. Terraform permanently deletes configuration versions marked for soft deletion after a set number of days unless the configuration version is restored. Once a configuration version is soft deleted, any attempts to read the configuration version will fail. Refer to [Configuration Version States](#configuration-version-states) for information about all data states. + +This endpoint can only soft delete configuration versions that meet the following criteria: + +- Were created using the API or CLI, +- are in an [`uploaded` state](#configuration-version-states), +- and are not the current configuration version. + +Otherwise, the endpoint returns an error. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [200][] | none | Terraform successfully marked the data for garbage collection. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_soft_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the configuration version or the user is not authorized to modify the configuration version state. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/soft_delete_backing_data + --data {"data": {"attributes": {"delete-older-than-n-days": 23}}} +``` + +## Restore Configuration Versions Marked for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/configuration-versions/:configuration-id/actions/restore_backing_data` + +| Parameter | Description | +| ------------------- | ---------------------------------------------------------------------------------------- | +| `:configuration-id` | The ID of the configuration version to restore back to its uploaded state if applicable. | + +This endpoint directs Terraform Enterprise to restore backing files associated with this configuration version. This endpoint can only restore delete configuration versions that meet the following criteria: + +- are not in a [`backing_data_permanently_deleted` state](#configuration-version-states). + +Otherwise, the endpoint returns an error. Terraform restores applicable configuration versions back to their `uploaded` state. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [200][] | none | Terraform successfully initiated the restore process. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `uploaded`. | +| [404][] | [JSON API error object][] | Terraform did not find the configuration version or the user is not authorized to modify the configuration version state. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/restore_backing_data +``` + +## Permanently Delete a Configuration Version + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/configuration-versions/:configuration-id/actions/permanently_delete_backing_data` + +| Parameter | Description | +| ------------------- | ---------------------------------------------------------- | +| `:configuration-id` | The ID of the configuration version to permanently delete. | + +This endpoint directs Terraform Enterprise to permanently delete backing files associated with this configuration version. This endpoint can only permanently delete configuration versions that meet the following criteria: + +- Were created using the API or CLI, +- are in a [`backing_data_soft_deleted` state](#configuration-version-states), +- and are not the current configuration version. + +Otherwise, the endpoint returns an error. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [200][] | none | Terraform successfully deleted the data permanently. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_permanently_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the configuration version or the user is not authorized to modify the configuration version state. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/permanently_delete_backing_data +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| -------------------- | ------------------------------------------------- | +| `ingress_attributes` | The commit information used in the configuration. | +| `run` | The run created by the configuration. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/cost-estimates.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/cost-estimates.mdx new file mode 100644 index 0000000000..a58a2b8481 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/cost-estimates.mdx @@ -0,0 +1,98 @@ +--- +page_title: /cost-estimates API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/cost-estimates` endpoint to read a cost + estimate using its ID. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Cost estimates API reference + +## Show a cost estimate + +-> **Note**: The hash in the `resources` attribute structure represents low-level Cost Estimation details. The keys or structure may change over time. Use the data in this hash at your own risk. + +`GET /cost-estimates/:id` + +| Parameter | Description | +| --------- | ------------------------------------ | +| `id` | The ID of the cost estimate to show. | + +There is no endpoint to list cost estimates. You can find the ID for a cost estimate in the +`relationships.cost-estimate` property of a run object. + +| Status | Response | Reason | +| ------- | ------------------------------------------------ | --------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "cost-estimates"`) | The request was successful | +| [404][] | [JSON API error object][] | Cost estimate not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/cost-estimates/ce-BPvFFrYCqRV6qVBK +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ce-BPvFFrYCqRV6qVBK", + "type": "cost-estimates", + "attributes": { + "error-message": null, + "status": "finished", + "status-timestamps": { + "queued-at": "2017-11-29T20:02:17+00:00", + "finished-at": "2017-11-29T20:02:20+00:00" + }, + "resources": {...}, + "resources-count": 4, + "matched-resources-count": 3, + "unmatched-resources-count": 1, + "prior-monthly-cost": "0.0", + "proposed-monthly-cost": "25.488", + "delta-monthly-cost": "25.488", + }, + "links": { + "self": "/api/v2/cost-estimate/ce-9VYRc9bpfJEsnwum" + } + } + ] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/data-retention-policies.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/data-retention-policies.mdx new file mode 100644 index 0000000000..2678528ba8 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/data-retention-policies.mdx @@ -0,0 +1,291 @@ +--- +page_title: /data-retention-policy API endpoint reference +description: >- + Use the `/data-retention-policy` endpoint to configure data storage policy. Learn how to call the data retention policy endpoint to delete data after a specific number of days. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + + +# Data retention policy API + +Data retention policies allow administrators to control storage usage by specifying how long backing data is retained for different resources. + +A data retention policy determines when Terraform Enterprise automatically marks _backing data_ for garbage collection. Backing data refers to [configuration version](/terraform/enterprise/api-docs/configuration-versions) or [state version](/terraform/enterprise/api-docs/state-versions) files. + +You can set data retention policies per workspace, organization, and Terraform Enterprise installation. +## Default policy settings + +When the data retention policy is unspecified for a workspace, the workspace inherits the data retention policy defined for the organization. Refer to [Data Retention Policies](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) in the workspace settings documentation for additional information. + +When the data retention policy is unspecified for an organization, the organization inherits the [global data retention policy](/terraform/enterprise/application-administration/general#data-retention-policies). Refer to [Data Retention Policies](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) in the organization settings documentation for additional information. + + +## Show data retention policy + +This endpoint shows the data retention policy set on the target resource. + +| Resource | API Endpoint | +| --------------| ----------------------------------------------- | +| [Workspaces](/terraform/enterprise/api-docs/workspaces#show-data-retention-policy) | `GET /workspaces/:workspace_id/relationships/data-retention-policy` | +| [Organizations](/terraform/enterprise/api-docs/organizations#show-data-retention-policy) | `GET /organizations/:organization_name/relationships/data-retention-policy` | +| [Site-wide](/terraform/enterprise/api-docs/admin/settings#show-data-retention-policy) | `GET /admin/data-retention-policy-settings` | + +For more information on the types of data retention policies, and the keys returned for each, refer to [Data Retention Policy Types](#data-retention-policy-types) + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] with `type` set to `"data-retention-policy-delete-olders"` or `"data-retention-policy-dont-deletes"` | Successful request. Refer to [Data Retention Policy Types](#data-retention-policy-types). | +| [404][] | [JSON API error object][] | Target resource not found, data retention policy does not exist, or user unauthorized to perform action. | + +### Request body + +No request body. + +### Sample request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/relationships/data-retention-policy +``` + +### Sample response + +```json +{ + "data": { + "id": "drp-Kh74zpKVGNWbpugQ", + "type": "data-retention-policy-delete-olders", + "attributes": { + "delete-older-than-n-days": 60 + }, + "relationships": { + "target": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` + +## Create or update data retention policy + +This endpoint creates a data retention policy attached to a target resource or updates the existing policy. + +| Resource | API Endpoint | +| --------------| ----------------------------------------------- | +| [Workspaces](/terraform/enterprise/api-docs/workspaces#create-or-update-data-retention-policy) | `POST /workspaces/:workspace_id/relationships/data-retention-policy` | +| [Organizations](/terraform/enterprise/api-docs/organizations#create-or-update-data-retention-policy) | `POST /organizations/:organization_name/relationships/data-retention-policy` | +| [Site-wide](/terraform/enterprise/api-docs/admin/settings#create-or-update-data-retention-policy) | `POST /admin/data-retention-policy-settings` | + +You can also call the endpoint to change the type of the data retention policy. Sending a `POST` or `PATCH` request and specifying a different type of policy in the payload automatically creates the new data retention policy for the target resource to replace the existing policy. +For more information on the types of data retention policies, refer to [Data Retention Policy Types](#data-retention-policy-types). + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No content | Successfully updated the target resource's data retention policy. | +| [404][] | [JSON API error object][] | Target resource not found or user is not authorized to perform action. | + +### Request body + +This `POST` endpoint requires a JSON object with the following properties as a request payload: + +| Key path | Type | Description | +| ----------------- | ------ | ------------------------------ | +| `data.type` | string | A [data retention policy type](#data-retention-policy-types) | +| `data.attributes` | object | The attributes for the specified [policy type](#data-retention-policy-types) | + +### Sample payload + +```json +{ + "data": { + "type": "data-retention-policy-delete-olders", + "attributes": { + "deleteOlderThanNDays": 33 + } + } +} +``` + +### Sample request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/data-retention-policy +``` + +### Sample response + +```json +{ + "data": { + "id": "drp-Kh74zpKVGNWbpugQ", + "type": "data-retention-policy-delete-olders", + "attributes": { + "delete-older-than-n-days": 33 + }, + "relationships": { + "target": { + "data": { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + } + } + } +} +``` + +## Remove data retention policy + +This endpoint removes the data retention policy explicitly set on a target resource. + +| Resource | API Endpoint | +| --------------| ----------------------------------------------- | +| [Workspaces](/terraform/enterprise/api-docs/workspaces#remove-data-retention-policy) | `DELETE /workspaces/:workspace_id/relationships/data-retention-policy` | +| [Organizations](/terraform/enterprise/api-docs/organizations#remove-data-retention-policy) | `DELETE /organizations/:organization_name/relationships/data-retention-policy` | +| [Site-wide](/terraform/enterprise/api-docs/admin/settings#remove-data-retention-policy) | `DELETE /admin/data-retention-policy-settings` | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully removed the target resource's data retention policy. | +| [404][] | [JSON API error object][] | Target resource not found, or user unauthorized to perform action. | + +### Request body + +No request body. + +### Sample request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp/relationships/data-retention-policy +``` + +### Response + +No response body. + +Status code `204`. + +## Data retention policy types + +You can send a `POST` or `PATCH` request to `/data-retention-policy` and `/data-retention-policy-settings` endpoints to set the policy or change the existing policy. The schema for each type has a set of attributes that are specific to the type. + +Specify one of the following data retention policy types in the `data.type` parameter in the request payload: + +- `data-retention-policy-delete-olders`: Directs Terraform Enterprise to delete backing data older than a set number of days. Refer to [`data-retention-policy-delete-olders`](#data-retention-policy-delete-olders) for additional information. +- `data-retention-policy-dont-deletes`: Directs Terraform Enterprise to preserve backing data for the related resource. Refer to [`data-retention-policy-dont-deletes`](#data-retention-policy-dont-deletes) for additional information. + +To view the existing policy, send a `GET` request to the endpoint. Endpoints are polymorphic and may return different policy types depending on how Terraform Enterprise has been configured. + +### `data-retention-policy-delete-olders` + +This policy directs Terraform Enterprise to delete backing data older than a set number of days. + +### Properties + +| Key path | Type | Description | +| -------------------------------------- | ------- | ---------------------------------------------- | +| `data.type` | string | Must be `data-retention-policy-delete-olders`. | +| `data.attributes.deleteOlderThanNDays` | integer | The number of days to retain backing data for. | +| `data.relationships.target` | object | The resource the policy is attached to. An organization, workspace, or `null` for the site-wide policy. Cannot be updated directly. | + +### Sample payload + +```json +{ + "data": { + "type": "data-retention-policy-delete-olders", + "attributes": { + "deleteOlderThanNDays": 33 + } + } +} +``` + +### Sample response body + +```json +{ + "data": { + "id": "drp-Kh74zpKVGNWbpugQ", + "type": "data-retention-policy-delete-olders", + "attributes": { + "delete-older-than-n-days": 33 + }, + "relationships": { + "target": { + "data": { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + } + } + } +} +``` + +### `data-retention-policy-dont-deletes` + +This policy directs Terraform Enterprise to preserve backing data for the related resource. + +### Properties + +| Key path | Type | Description | +| -------------------------------------- | ------- | ---------------------------------------------- | +| `data.type` | string | Must be `data-retention-policy-dont-deletes`. | +| `data.attributes` | object | Not applicable. This policy type does not have attributes. | +| `data.relationships.target` | object | The resource the policy is attached to. An organization, workspace. Cannot be updated directly. | + +### Sample payload + +```json +{ + "data": { + "type": "data-retention-policy-dont-deletes", + "attributes": {} + } +} +``` + +### Sample response body + +```json +{ + "data": { + "id": "drp-Kh74zpKVGNWbpugQ", + "type": "data-retention-policy-dont-deletes", + "attributes": {}, + "relationships": { + "target": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/github-app-installations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/github-app-installations.mdx new file mode 100644 index 0000000000..8573467c08 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/github-app-installations.mdx @@ -0,0 +1,127 @@ +--- +page_title: /github-app/installations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/github-app/installations` endpoint to + view details about where you have installed the Terraform Enterprise GitHub + App. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# GitHub App installations API reference + +You can create a GitHub App installation using the HCP Terraform UI. Learn how to [create a GitHub App installation](/terraform/enterprise/vcs/github-app). + +~> **Note:** To use this resource in Terraform Enterprise installations, you must configure the GitHub App in the site admin area. + +~> **Note:** You can only use this API if you have already authorized the Terraform Cloud GitHub App. Manage your [GitHub App token](/terraform/enterprise/users-teams-organizations/users#github-app-oauth-token) from **Account Settings** > **Tokens**. + +## List Installations + +This endpoint lists GitHub App installations available to the current user. + +`GET /github-app/installations` + +### Query Parameters + +Queries only return GitHub App Installations that the current user has access to within GitHub. + +| Parameter | Description | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[name]` | **Optional.** If present, returns a list of available GitHub App installations that match the GitHub organization or login. | +| `filter[installation_id]` | **Optional.** If present, returns a list of available GitHub App installations that match the installation ID within GitHub. (**Not HCP Terraform**) | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/github-app/installations +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ghain-BYrbNeGQ8nAzKouu", + "type": "github-app-installations", + "attributes": { + "name": "octouser", + "installation-id": 54810170, + "icon-url": "https://avatars.githubusercontent.com/u/29916665?v=4", + "installation-type": "User", + "installation-url": "https://github.com/settings/installations/54810170" + } + } + ] +} +``` + +## Show Installation + +`GET /github-app/installation/:gh_app_installation_id` + +| Parameter | Description | +| ------------------------- | ------------------------------ | +| `:gh_app_installation_id` | The Github App Installation ID | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/github-app/installation/ghain-R4xmKTaxnhLFioUq +``` + +### Sample Response + +```json +{ + "data": { + "id": "ghain-R4xmKTaxnhLFioUq", + "type": "github-app-installations", + "attributes": { + "name": "octouser", + "installation-id": 54810170, + "icon-url": "https://avatars.githubusercontent.com/u/29916665?v=4", + "installation-type": "User", + "installation-url": "https://github.com/settings/installations/54810170" + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/index.mdx new file mode 100644 index 0000000000..9615d628e4 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/index.mdx @@ -0,0 +1,374 @@ +--- +page_title: API documentation for Terraform Enterprise +description: >- + Learn about API authentication, response codes, versioning, formatting, rate + limiting, and clients. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# HCP Terraform API documentation + +HCP Terraform provides an API for a subset of its features. If you need assistance or want to submit a feature request, visit the [HashiCorp support center](https://support.hashicorp.com/hc/en-us) and open a ticket. + +-> **Note:** Before planning an API integration, consider whether [the `tfe` Terraform provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) meets your needs. It can't create or approve runs in response to arbitrary events, but it's a useful tool for managing your organizations, teams, and workspaces as code. + +HashiCorp provides a [stability policy](/terraform/enterprise/api-docs/stability-policy) for the HCP Terraform API, ensuring backwards compatibility for stable endpoints. The [changelog](/terraform/enterprise/api-docs/changelog) tracks changes to the API for HCP Terraform and Terraform Enterprise. + +## Authentication + +All requests must be authenticated with a bearer token. Use the HTTP header `Authorization` with the value `Bearer `. If the token is absent or invalid, HCP Terraform responds with [HTTP status 401][401] and a [JSON API error object][]. The 401 status code is reserved for problems with the authentication token; forbidden requests with a valid token result in a 404. + +You can use the following types of tokens to authenticate: + +- [User tokens](/terraform/enterprise/users-teams-organizations/users#api-tokens) — each HCP Terraform user can have any number of API tokens, which can make requests on their behalf. +- [Team tokens](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) — each team can have one API token at a time. This is intended for performing plans and applies via a CI/CD pipeline. +- [Organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) — each organization can have one API token at a time. This is intended for automating the management of teams, team membership, and workspaces. The organization token cannot perform plans and applies. + +- [Audit trails token](/terraform/enterprise/users-teams-organizations/api-tokens#audit-trails-tokens) - each organization can have a single token that can read that organization's audit trails. Use this token type to authenticate integrations pulling audit trail data, for example, using the [HCP Terraform for Splunk](/terraform/enterprise/integrations/splunk) app. + + +### Blob Storage Authentication + +HCP Terraform relies on a HashiCorp-developed blob storage service for storing statefiles and multiple other pieces of customer data, all of which are documented on our [data security page](/terraform/enterprise/architectural-details/data-security). + +Unlike the HCP Terraform API, this service does not require that a bearer token be submitted with each request. Instead, each URL includes a securely generated secret and is only valid for 25 hours. + +For example, the [state versions api](/terraform/enterprise/api-docs/state-versions) returns a field named `hosted-state-download`, which is a URL of this form: +`https://archivist.terraform.io/v1/object/` + +This is a broadly accepted pattern for secure access. It is important to treat these URLs themselves as secrets. They should not be logged, nor shared with untrusted parties. + +## Feature Entitlements + +HCP Terraform is available at multiple pricing tiers (including free), which offer different feature sets. + +Each organization has a set of _entitlements_ that corresponds to its pricing tier. These entitlements determine which HCP Terraform features the organization can use. + +If an organization doesn't have the necessary entitlement to use a given feature, HCP Terraform returns a 404 error for API requests to any endpoints devoted to that feature. + +The [show entitlement set](/terraform/enterprise/api-docs/organizations#show-the-entitlement-set) endpoint can return information about an organization's current entitlements, which is useful if your client needs to change its interface when a given feature isn't available. + +The following entitlements are available: + +- `agents` — Allows isolated, private or on-premises infrastructure to communicate with an organization in HCP Terraform. Affects the [agent pools][], [agents][], and [agent tokens][] endpoints. + +- `audit-logging` — Allows an organization to access [audit trails][]. + +- `configuration-designer` — Allows an organization to use the [Configuration Designer][]. +- `cost-estimation` — Allows an organization to access [cost estimation][]. +- `global-run-tasks` — Allows an organization to apply [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) to every workspace. Affects the [run tasks][] endpoints. This feature is currently in beta. +- `module-tests-generation` - Allows an organization to generate tests for private registry modules. This feature is currently in beta. +- `operations` — Allows an organization to perform runs within HCP Terraform. Affects the [runs][], [plans][], and [applies][] endpoints. +- `policy-enforcement` — Allows an organization to use [Sentinel][]. Affects the [policies][], [policy sets][], and [policy checks][] endpoints. +- `private-module-registry` — Allows an organization to publish and use modules with the [private module registry][]. Affects the [registry modules][] endpoints. +- `private-policy-agents` - Allows an organization to ensure that HTTP enabled [Sentinel][] and OPA [policies][] can communicate with isolated, private, or on-premises infrastructure. +- `run-tasks` — Allows an organization to use [run tasks](/terraform/enterprise/workspaces/settings/run-tasks). Affects the [run tasks][] endpoints. +- `self-serve-billing` — Allows an organization to pay via credit card using the in-app billing UI. +- `sentinel` - **DEPRECATED** Use `policy-enforcement` instead. +- `state-storage` — Allows an organization to store state versions in its workspaces, which enables local Terraform runs with HCP Terraform. Affects the [state versions][] endpoints. +- `sso` — Allows an organization to manage and authenticate users with single sign on. +- `teams` — Allows an organization to manage access to its workspaces with [teams](/terraform/enterprise/users-teams-organizations/teams). Without this entitlement, an organization only has an owners team. Affects the [teams][], [team members][], [team access][], and [team tokens][] endpoints. +- `user-limit` — An integer value representing the maximum number of users allowed for the organization. If blank, there is no limit. +- `vcs-integrations` — Allows an organization to [connect with a VCS provider][vcs integrations] and link VCS repositories to workspaces. Affects the [OAuth Clients][o-clients], and [OAuth Tokens][o-tokens] endpoints, and determines whether the `data.attributes.vcs-repo` property can be set for [workspaces][]. + +[agents]: /terraform/enterprise/api-docs/agents + +[agent pools]: /terraform/enterprise/api-docs/agents + +[agent tokens]: /terraform/enterprise/api-docs/agent-tokens + +[applies]: /terraform/enterprise/api-docs/applies + + + +[audit trails]: /terraform/enterprise/api-docs/audit-trails + + + +[Configuration Designer]: /terraform/enterprise/registry/design + +[cost estimation]: /terraform/enterprise/cost-estimation + +[o-clients]: /terraform/enterprise/api-docs/oauth-clients + +[o-tokens]: /terraform/enterprise/api-docs/oauth-tokens + +[plans]: /terraform/enterprise/api-docs/plans + +[policies]: /terraform/enterprise/api-docs/policies + +[policy checks]: /terraform/enterprise/api-docs/policy-checks + +[policy sets]: /terraform/enterprise/api-docs/policy-sets + +[private module registry]: /terraform/enterprise/registry + +[registry modules]: /terraform/enterprise/api-docs/private-registry/modules + +[registry providers]: /terraform/enterprise/api-docs/private-registry/providers + +[runs]: /terraform/enterprise/api-docs/run + +[run tasks]: /terraform/enterprise/api-docs/run-tasks/run-tasks + +[Sentinel]: /terraform/enterprise/policy-enforcement/sentinel + +[single sign on]: /terraform/enterprise/users-teams-organizations/single-sign-on + +[state versions]: /terraform/enterprise/api-docs/state-versions + +[teams]: /terraform/enterprise/api-docs/teams + +[team access]: /terraform/enterprise/api-docs/team-access + +[team members]: /terraform/enterprise/api-docs/team-members + +[team tokens]: /terraform/enterprise/api-docs/team-tokens + +[vcs integrations]: /terraform/enterprise/vcs + +[workspaces]: /terraform/enterprise/api-docs/workspaces + +## Response Codes + +This API returns standard HTTP response codes. + +We return 404 Not Found codes for resources that a user doesn't have access to, as well as for resources that don't exist. This is to avoid telling a potential attacker that a given resource exists. + +## Versioning + +The API documented in these pages is the second version of HCP Terraform's API, and resides under the `/v2` prefix. + +Future APIs will increment this version, leaving the `/v1` API intact, though in the future we might deprecate certain features. In that case, we'll provide ample notice to migrate to the new API. + +## Paths + +All V2 API endpoints use `/api/v2` as a prefix unless otherwise specified. + +For example, if the API endpoint documentation defines the path `/runs` then the full path is `/api/v2/runs`. + +## JSON API Formatting + +The HCP Terraform endpoints use the [JSON API specification](https://jsonapi.org/), which specifies key aspects of the API. Most notably: + +- [HTTP error codes](https://jsonapi.org/examples/#error-objects-error-codes) +- [Error objects](https://jsonapi.org/examples/#error-objects-basics) +- [Document structure][document] +- [HTTP request/response headers](https://jsonapi.org/format/#content-negotiation) + +[document]: https://jsonapi.org/format/#document-structure + +### JSON API Documents + +Since our API endpoints use the JSON API spec, most of them return [JSON API documents][document]. + +Endpoints that use the POST method also require a JSON API document as the request payload. A request object usually looks something like this: + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "category":"terraform", + "hcl":false, + "sensitive":false + }, + "relationships": { + "workspace": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + } + } + } + } +} +``` + +These objects always include a top-level `data` property, which: + +- Must have a `type` property to indicate what type of API object you're interacting with. +- Often has an `attributes` property to specify attributes of the object you're creating or modifying. +- Sometimes has a `relationships` property to specify other objects that are linked to what you're working with. + +In the documentation for each API method, we use dot notation to explain the structure of nested objects in the request. For example, the properties of the request object above are listed as follows: + +| Key path | Type | Default | Description | +| ---------------------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | | The value of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the variable is written once and not visible thereafter. | +| `data.relationships.workspace.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.workspace.data.id` | string | | The ID of the workspace that owns the variable. | + +We also always include a sample payload object, to show the document structure more visually. + +### Query Parameters + +Although most of our API endpoints use the POST method and receive their parameters as a JSON object in the request payload, some of them use the GET method. These GET endpoints sometimes require URL query parameters, in the standard `...path?key1=value1&key2=value2` format. + +Since these parameters were originally designed as part of a JSON object, they sometimes have characters that must be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) in a query parameter. For example, `[` becomes `%5B` and `]` becomes `%5D`. + +For more about URI structure and query strings, see [the specification (RFC 3986)](https://tools.ietf.org/html/rfc3986) or [the Wikipedia page on URIs](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier). + +### Pagination + +Most of the endpoints that return lists of objects support pagination. A client may pass the following query parameters to control pagination on supported endpoints: + +| Parameter | Description | +| -------------- | --------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 items per page. The maximum page size is 100. | + +Additional data is returned in the `links` and `meta` top level attributes of the response. + +```json +{ + "data": [...], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20", + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": 2, + "total-pages": 2, + "total-count": 21 + } + } +} +``` + +### Inclusion of Related Resources + +Some of the API's GET endpoints can return additional information about nested resources by adding an `include` query parameter, whose value is a comma-separated list of resource types. + +The related resource options are listed in each endpoint's documentation where available. + +The related resources will appear in an `included` section of the response. + +Example: + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/teams/team-n8UQ6wfhyym25sMe?include=users +``` + +```json +{ + "data": { + "id": "team-n8UQ6wfhyym25sMe", + "type": "teams", + "attributes": { + "name": "owners", + "users-count": 1 + ... + }, + "relationships": { + "users": { + "data": [ + { + "id": "user-62goNpx1ThQf689e", + "type": "users" + } + ] + } ... + } + ... + }, + "included": [ + { + "id": "user-62goNpx1ThQf689e", + "type": "users", + "attributes": { + "username": "hashibot" + ... + } ... + } + ] +} +``` + +## Rate Limiting + +You can make up to 30 requests per second to the API as an authenticated or unauthenticated request. If you reach the rate limit then your access will be throttled and an error response will be returned. Some endpoints have lower rate limits to prevent abuse, including endpoints that poll Terraform for a list of runs and endpoints related to user authentication. The adjusted limits are unnoticeable under normal use. If you receive a rate-limited response, the limit is reflected in the `x-ratelimit-limit` header once triggered. + +Authenticated requests are allocated to the user associated with the authentication token. This means that a user with multiple tokens will still be limited to 30 requests per second, additional tokens will not allow you to increase the requests per second permitted. + +Unauthenticated requests are associated with the requesting IP address. + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------- | +| [429][] | [JSON API error object][] | Rate limit has been reached. | + +```json +{ + "errors": [ + { + "detail": "You have exceeded the API's rate limit.", + "status": 429, + "title": "Too many requests" + } + ] +} +``` + +## Client libraries and tools + +HashiCorp maintains [go-tfe](https://github.com/hashicorp/go-tfe), a Go client for HCP Terraform's API. + +Additionally, the community of HCP Terraform users and vendors have built client libraries in other languages. These client libraries and tools are not tested nor officially maintained by HashiCorp, but are listed below in order to help users find them easily. + +If you have built a client library and would like to add it to this community list, please [contribute](https://github.com/hashicorp/terraform-website#contributions-welcome) to [this page](https://github.com/hashicorp/terraform-docs-common/blob/main/website/docs/cloud-docs/api-docs/index.mdx#client-libraries-and-tools). + +- [tfh](https://github.com/hashicorp-community/tf-helper): UNIX shell console app +- [tf_api_gateway](https://github.com/PlethoraOfHate/tf_api_gateway): Python API library and console app +- [terrasnek](https://github.com/dahlke/terrasnek): Python API library +- [terraform-enterprise-client](https://github.com/skierkowski/terraform-enterprise-client): Ruby API library and console app +- [pyterprise](https://github.com/JFryy/terraform-enterprise-api-python-client): A simple Python API client library. +- [Tfe.NetClient](https://github.com/everis-technology/Tfe.NetClient): .NET Client Library diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/no-code-provisioning.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/no-code-provisioning.mdx new file mode 100644 index 0000000000..c8c0bfd9f9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/no-code-provisioning.mdx @@ -0,0 +1,924 @@ +--- +page_title: /no-code-modules API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/no-code-modules` endpoint to designate + and configure no-code modules. You can also use this endpoint to deploy and + upgrade no-code workspaces. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: http://jsonapi.org/format/#error-objects + +# No-code provisioning API reference + +The no-code provisioning API allows you to create, configure, and deploy Terraform modules in the no-code provisioning workflows within HCP Terraform. For more information on no-code modules, refer to [Designing No-Code Ready Modules](/terraform/enterprise/no-code-provisioning/module-design). + +## Enable no-code provisioning for a module + +`POST /organizations/:organization_name/no-code-modules` + +| Parameter | Description | +| -------------------- | --------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | + +To deploy a module using the no-code provisioning workflow, the module must meet the following requirement: + +1. The module must exist in your organization's private registry. +2. The module must meet the [design requirements](/terraform/enterprise/no-code-provisioning/module-design#requirements) for a no-code module. +3. You must enable no-code provisioning for the module. + +You can send a `POST` request to the `/no-code-modules` endpoint to enable no-code provisioning for a specific module. You can also call this endpoint to set options for the allowed values of a variable for a no-code module in your organization. + +-> **Note**: This endpoint can not be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "no-code-modules"`) | Successfully enabled a module for no-code provisioning. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------------------------------- | ------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"no-code-modules"`. | +| `data.attributes.version-pin` | string | Latest version of the module | The module version to use in no-code provisioning workflows. | +| `data.attributes.enabled` | boolean | `false` | Set to `true` to enable no-code provisioning workflows. | +| `data.relationships.registry-module.data.id` | string | | The ID of a module in the organization's private registry. | +| `data.relationships.registry-module.data.type` | string | | Must be `"registry-module"`. | +| `data.relationships.variable-options.data[].type` | string | | Must be `"variable-options"`. | +| `data.relationships.variable-options.data[].attributes.variable-name` | string | | The name of a variable within the module. | +| `data.relationships.variable-options.data[].attributes.variable-type` | string | | The data type for the variable. Can be [any type supported by Terraform](/terraform/language/expressions/types#types). | +| `data.relationships.variable-options.data[].attributes.options` | Any\[] | | A list of allowed values for the variable. | + +### Sample Payload + +```json +{ + "data": { + "type": "no-code-modules", + "attributes": { + "version-pin": "1.0.1", + "enabled": true + }, + "relationships": { + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-module" + } + }, + "variable-options": { + "data": [ + { + "type": "variable-options", + "attributes": { + "variable-name": "amis", + "variable-type": "string", + "options": [ + "ami-1", + "ami-2", + "ami-3" + ] + } + }, + { + "type": "variable-options", + "attributes": { + "variable-name": "region", + "variable-type": "string", + "options": [ + "eu-north-1", + "us-east-2", + "us-west-1" + ] + } + } + ] + } + } + } +} + +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/no-code-modules +``` + +### Sample Response + +```json +{ + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-modules", + "attributes": { + "enabled": true, + "version-pin": "1.0.1" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-modules" + }, + "links": { + "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options" + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options" + } + ] + } + }, + "links": { + "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2" + } + } +} +``` + +## Update no-code provisioning settings + +`PATCH /no-code-modules/:id` + +| Parameter | Description | +| --------- | -------------------------------------------- | +| `:id` | The unique identifier of the no-code module. | + +Send a `PATCH` request to the `/no-code-modules/:id` endpoint to update the settings for the no-code provisioning of a module. You can update the following settings: + +- Enable or disable no-code provisioning. +- Adjust the set of options for allowed variable values. +- Change the module version being provisioned. +- Change the module being provisioned. + +The [API call that enables no-code provisioning for a module](#allow-no-code-provisioning-of-a-module-within-an-organization) returns that module's unique identifier. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "no-code-modules"`) | Successfully updated a no-code module. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------------------------------- | ------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"no-code-modules"`. | +| `data.attributes.version-pin` | string | Existing value | The module version to use in no-code provisioning workflows. | +| `data.attributes.enabled` | boolean | Existing value | Set to `true` to enable no-code provisioning workflows, or `false` to disable them. | +| `data.relationships.registry-module.data.id` | string | Existing value | The ID of a module in the organization's Private Registry. | +| `data.relationships.registry-module.data.type` | string | Existing value | Must be `"registry-module"`. | +| `data.relationships.variable-options.data[].id` | string | | The ID of an existing variable-options set. If provided, a new variable-options set replaces the set with this ID. If not provided, this creates a new variable-option set. | +| `data.relationships.variable-options.data[].type` | string | | Must be `"variable-options"`. | +| `data.relationships.variable-options.data[].attributes.variable-name` | string | | The name of a variable within the module. | +| `data.relationships.variable-options.data[].attributes.variable-type` | string | | The data type for the variable. Can be [any type supported by Terraform](/terraform/language/expressions/types#types). | +| `data.relationships.variable-options.data[].attributes.options` | Any\[] | | A list of allowed values for the variable. | + +### Sample Payload + +```json +{ + "data": { + "type": "no-code-modules", + "attributes": { + "enabled": false + }, + "relationships": { + "registry-module": { + "data": { + "id": "mod-zyai9dwH4VPPaVuC", + "type": "registry-module" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options", + "attributes": { + "variable-name": "Linux AMIs", + "variable-type": "array", + "options": [ + "Xenial Xerus", + "Trusty Tahr" + ] + } + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options", + "attributes": { + "variable-name": "region", + "variable-type": "array", + "options": [ + "eu-north-1", + "us-east-2", + "us-west-1" + ] + } + } + ] + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2 +``` + +### Sample Response + +```json +{ + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-modules", + "attributes": { + "enabled": true, + "version-pin": "1.0.1" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-modules" + }, + "links": { + "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options" + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options" + } + ] + } + }, + "links": { + "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2" + } + } +} +``` + +## Read a no-code module's properties + +`GET /no-code-modules/:id` + +| Parameter | Description | +| --------- | -------------------------------------------- | +| `:id` | The unique identifier of the no-code module. | + +Use this API to read the details of an existing no-code module. + +The [API call that enables no-code provisioning for a module](#allow-no-code-provisioning-of-a-module-within-an-organization) returns that module's unique identifier. + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "no-code-modules"`) | Successfully read the no-code module. | +| [400][] | [JSON API error object][] | Invalid `include` parameter. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Query Parameters + +This endpoint uses our [standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Use HTML URL encoding syntax, such as `%5B` to represent `[` and `%5D` to represent `]`, if your tooling does not automatically encode URLs. + +Terraform returns related resources when you add the [`include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources) to the request. + +| Parameter | Description | +| --------- | ------------------------------------------------- | +| `include` | List related resource to include in the response. | + +The following resource types are available: + +| Resource Name | Description | +| ------------------ | --------------------------------------------------------- | +| `variable_options` | Module variables with a configured set of allowed values. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2?include=variable_options +``` + +### Sample Response + +```json +{ + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-modules", + "attributes": { + "enabled": true, + "version-pin": "1.0.1" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-modules" + }, + "links": { + "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options" + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options" + } + ] + } + }, + "links": { + "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2" + } + }, + "included": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options", + "attributes": { + "variable-name": "Linux AMIs", + "variable-type": "array", + "options": [ + "Xenial Xerus", + "Trusty Tahr" + ] + }, + "relationships": { + "no-code-allowed-module": { + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-allowed-modules" + } + } + } + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options", + "attributes": { + "variable-name": "region", + "variable-type": "array", + "options": [ + "eu-north-1", + "us-east-2", + "us-west-1" + ] + }, + "relationships": { + "no-code-allowed-module": { + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-allowed-modules" + } + } + } + } + ] +} +``` + +## Create a no-code module workspace + +This endpoint creates a workspace from a no-code module. + +`POST /no-code-modules/:id/workspaces` + +| Parameter | Description | +| --------- | ------------------------------------------ | +| `:id` | The ID of the no-code module to provision. | + +Each HCP Terraform organization has a list of which modules you can use to create workspaces using no-code provisioning. You can use this API to create a workspace by selecting a no-code module to enable a no-code provisioning workflow. + +-> **Note**: This endpoint can not be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | -------------------------------------------- | -------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully created a workspace from a no-code module for no-code provisioning. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | | +| ------------------------------------------------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | +| `data.type` | string | none | Must be `"workspaces"`. | | +| `data.attributes.agent-pool-id` | string | none | Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote`. | | +| `data.attributes.auto_apply` | boolean | `false` | If `true`, Terraform automatically applies changes when a Terraform `plan` is successful. | | +| `data.attributes.description` | string | `""` | A description for the workspace. | | +| `data.attributes.execution-mode` | string | none | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use. Valid values are `remote`, and `agent`. When not provided, defaults to `remote`. | | +| `data.attributes.name` | string | none | The name of the workspace. You can only include letters, numbers, `-`, and `_`. Terraform uses this value to identify the workspace and must be unique in the organization. | | +| `data.attributes.source-name` | string | none | A friendly name for the application or client creating this workspace. If set, this will be displayed on the workspace as "Created via ``". | | +| `data.attributes.source-url` | string | (nothing) | A URL for the application or client creating this workspace. This can be the URL of a related resource in another app, or a link to documentation or other info about the client. | | +| `data.attributes.terraform-version` | string | latest release | Specifies the version of Terraform to use for this workspace. You can specify an exact version or a [version constraint](/terraform/language/expressions/version-constraints) such as `~> 1.0.0`. If you specify a constraint, the workspace always uses the newest release that meets that constraint. If omitted when creating a workspace, this defaults to the latest released version. | | +| `data.relationships.project.data.id` | string | | The ID of the project to create the workspace in. You must have permission to create workspaces in the project, either by organization-level permissions or team admin access to a specific project. | | +| `data.relationships.project.data.type` | string | | Must be `"project"`. | | +| `data.relationships.vars.data[].type` | string | | Must be `"vars"`. | | +| `data.relationships.vars.data[].attributes.key` | string | | The name of the variable. | | +| `data.relationships.vars.data[].attributes.value` | string | `""` | The value of the variable. | | +| `data.relationships.vars.data[].attributes.description` | string | | The description of the variable. | | +| `data.relationships.vars.data[].attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | | +| `data.relationships.vars.data[].attributes.hcl` | boolean | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | | +| `data.relationships.vars.data[].attributes.sensitive` | boolean | `false` | Whether the value is sensitive. If `true` then the variable is written once and not visible thereafter. | | + +### Sample Payload + +```json +{ + "data": { + "type": "workspaces", + "attributes": { + "name": "no-code-workspace", + "description": "A workspace to enable the no-code provisioning workflow." + }, + "relationships": { + "project": { + "data": { + "id": "prj-yuEN6sJVra5t6XVy", + "type": "project" + } + }, + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "region", + "value": "eu-central-1", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + }, + { + "type": "vars", + "attributes": { + "key": "ami", + "value": "ami‑077062", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + } + ] + } + } + } +} + +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces +``` + +### Sample Response + +```json +{ + "data": { + "id": "ws-qACTToFUM5BvDKhC", + "type": "workspaces", + "attributes": { + "allow-destroy-plan": true, + "auto-apply": false, + "auto-destroy-at": null, + "auto-destroy-status": null, + "created-at": "2023-09-08T10:36:04.391Z", + "environment": "default", + "locked": false, + "name": "no-code-workspace", + "queue-all-runs": false, + "speculative-enabled": true, + "structured-run-output-enabled": true, + "terraform-version": "1.5.6", + "working-directory": null, + "global-remote-state": true, + "updated-at": "2023-09-08T10:36:04.427Z", + "resource-count": 0, + "apply-duration-average": null, + "plan-duration-average": null, + "policy-check-failures": null, + "run-failures": null, + "workspace-kpis-runs-count": null, + "latest-change-at": "2023-09-08T10:36:04.391Z", + "operations": true, + "execution-mode": "remote", + "vcs-repo": null, + "vcs-repo-identifier": null, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-queue-run": true, + "can-read-variable": true, + "can-update-variable": true, + "can-read-state-versions": true, + "can-read-state-outputs": true, + "can-create-state-versions": true, + "can-queue-apply": true, + "can-lock": true, + "can-unlock": true, + "can-force-unlock": true, + "can-read-settings": true, + "can-manage-tags": true, + "can-manage-run-tasks": true, + "can-force-delete": true, + "can-manage-assessments": true, + "can-manage-ephemeral-workspaces": true, + "can-read-assessment-results": true, + "can-queue-destroy": true + }, + "actions": { + "is-destroyable": true + }, + "description": null, + "file-triggers-enabled": true, + "trigger-prefixes": [], + "trigger-patterns": [], + "assessments-enabled": false, + "last-assessment-result-at": null, + "source": "tfe-module", + "source-name": null, + "source-url": null, + "source-module-id": "private/my-organization/lambda/aws/1.0.9", + "no-code-upgrade-available": false, + "tag-names": [], + "setting-overwrites": { + "execution-mode": false, + "agent-pool": false + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "current-run": { + "data": null + }, + "latest-run": { + "data": null + }, + "outputs": { + "data": [] + }, + "remote-state-consumers": { + "links": { + "related": "/api/v2/workspaces/ws-qACTToFUM5BvDKhC/relationships/remote-state-consumers" + } + }, + "current-state-version": { + "data": null + }, + "current-configuration-version": { + "data": { + "id": "cv-vizi2p3mnrt3utgA", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-vizi2p3mnrt3utgA" + } + }, + "agent-pool": { + "data": null + }, + "readme": { + "data": null + }, + "project": { + "data": { + "id": "prj-yuEN6sJVra5t6XVy", + "type": "projects" + } + }, + "current-assessment-result": { + "data": null + }, + "no-code-module-version": { + "data": { + "id": "nocodever-vFcQjZLs3ZHTe4TU", + "type": "no-code-module-versions" + } + }, + "vars": { + "data": [] + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/no-code-workspace", + "self-html": "/app/my-organization/workspaces/no-code-workspace" + } + } +} +``` + +## Initiate a no-code workspace update + +Upgrading a workspace's no-code provisioning settings is a multi-step process. + +1. Use this API to initiate the update. HCP Terraform starts a new plan, which describes the resources to add, update, or remove from the workspace. +2. Poll the [read workspace upgrade plan status API](#read-workspace-upgrade-plan-status) to wait for HCP Terraform to complete the plan. +3. Use the [confirm and apply a workspace upgrade plan API](#confirm-and-apply-a-workspace-upgrade-plan) to complete the workspace upgrade. + +`POST /no-code-modules/:no_code_module_id/workspaces/:id/upgrade` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:no_code_module_id` | The ID of the no-code module. | +| `:id` | The ID of the workspace. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.vars.data[].type` | string | | Must be `"vars"`. | +| `data.relationships.vars.data[].attributes.key` | string | | The name of the variable. | +| `data.relationships.vars.data[].attributes.value` | string | `""` | The value of the variable. | +| `data.relationships.vars.data[].attributes.description` | string | | The description of the variable. | +| `data.relationships.vars.data[].attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.relationships.vars.data[].attributes.hcl` | boolean | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.relationships.vars.data[].attributes.sensitive` | boolean | `false` | Whether the value is sensitive. If `true` then the variable is written once and not visible thereafter. | + +### Sample Payload + +```json +{ + "data": { + "type": "workspaces", + "relationships": { + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "region", + "value": "eu-central-1", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + }, + { + "type": "vars", + "attributes": { + "key": "ami", + "value": "ami‑077062", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + } + ] + } + } + } +} + +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-Cyij8ctBHM1g5xdX", + "type": "workspace-upgrade", + "attributes": { + "status": "planned", + "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-VvKtcfueHNkR6GqP", + "type": "workspaces" + } + } + } + } +} +``` + +## Read workspace upgrade plan status + +This endpoint returns the plan details and status for updating a workspace to new no-code provisioning settings. + +`GET /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:no_code_module_id` | The ID of the no-code module. | +| `:workspace_id` | The ID of workspace. | +| `:id` | The ID of update. | + +Returns the details of a no-code workspace update run, including the run's current state, such as `pending`, `fetching`, `planning`, `planned`, or `cost_estimated`. Refer to [Run States and Stages](/terraform/enterprise/run/states) for more information on the states a run can return. + +| Status | Response | Reason | +| ------- | --------------------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspace-upgrade"`) | Success | +| [404][] | [JSON API error object][] | Workspace upgrade not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-Cyij8ctBHM1g5xdX", + "type": "workspace-upgrade", + "attributes": { + "status": "planned_and_finished", + "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-VvKtcfueHNkR6GqP", + "type": "workspaces" + } + } + } + } +} +``` + +## Confirm and apply a workspace upgrade plan + +Use this endpoint to confirm an update and finalize the update for a workspace to use new no-code provisioning settings. + +`POST /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:no_code_module_id` | The ID of the no-code module. | +| `:workspace_id` | The ID of workspace. | +| `:id` | The ID of update. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX +``` + +### Sample Response + +```json +{ "Workspace update completed" } +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/notification-configurations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/notification-configurations.mdx new file mode 100644 index 0000000000..2fa78f811f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/notification-configurations.mdx @@ -0,0 +1,1437 @@ +--- +page_title: /notification-configurations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/notification-configurations` endpoint to + read, create, update, verify, and delete workspace configurations and create + team configurations. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Notification configurations API reference + +HCP Terraform can send notifications for run state transitions and workspace events. You can specify a destination URL, request type, and what events will trigger the notification. Each workspace can have up to 20 notification configurations, and they apply to all runs for that workspace. + +Interacting with notification configurations requires admin access to the relevant workspace. ([More about permissions](/terraform/enterprise/users-teams-organizations/permissions).) + +-> **Note:** [Speculative plans](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) and workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) do not support notifications. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Notification triggers + +Notifications are sent in response to triggers related to workspace events, and can be defined at workspace and team levels. You can specify workspace events in the `triggers` array attribute. + +### Workspace notification triggers + +The following triggers are available for workspace notifications. + +| Display Name | Value | Description | +| ------------------------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Created | `"run:created"` | A run is created and enters the [Pending stage](/terraform/enterprise/run/states#the-pending-stage) | +| Planning | `"run:planning"` | A run acquires the lock and starts to execute. | +| Needs Attention | `"run:needs_attention"` | A plan has changes and Terraform requires user input to continue. This input may include approving the plan or a [policy override](/terraform/enterprise/run/states#the-policy-check-stage). | +| Applying | `"run:applying"` | A run enters the [Apply stage](/terraform/enterprise/run/states#the-apply-stage), where Terraform makes the infrastructure changes described in the plan. | +| Completed | `"run:completed"` | A run completes successfully. | +| Errored | `"run:errored"` | A run terminates early due to error or cancellation. | +| Drifted | `"assessment:drifted"` | HCP Terraform detected configuration drift. This option is only available if you enabled drift detection for the workspace. | +| Checks Failed | `"assessment:check_failure"` | One or more continuous validation checks did not pass. This option is only available if you enabled drift detection for the workspace. | +| Health Assessment Failed | `"assessment:failed"` | A health assessment failed. This option is only available if you enable health assessments for the workspace. | +| Auto Destroy Reminder | `"workspace:auto_destro_reminder"` | An automated workspace destroy run is imminent. | +| Auto Destroy Results | `"workspace:auto_destroy_run_results"` | HCP Terraform attempted an automated workspace destroy run. | + +### Team notification triggers + +The following triggers are available for [team notifications](#team-notification-configuration). + +| Display Name | Value | Description | +| -------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| Change Request | `"team:change_request"` | HCP Terraform sent a change request to a workspace that the specified team has explicit access to. | + +## Notification payload + +The notification is an HTTP POST request with a detailed payload. The content depends on the type of notification. + +For Slack and Microsoft Teams notifications, the payload conforms to the respective webhook API and results in a notification message with informational attachments. Refer to [Slack Notification Payloads](/terraform/enterprise/workspaces/settings/notifications#slack) and [Microsoft Teams Notification Payloads](/terraform/enterprise/workspaces/settings/notifications#microsoft-teams) for examples. For generic notifications, the payload varies based on whether the notification contains information about run events or workspace events. + +### Run notification payload + +Run events include detailed information about a specific run, including the time it began and the associated workspace and organization. Generic notifications for run events contain the following information: + +| Name | Type | Description | +| -------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `payload_version` | number | Always "1". | +| `notification_configuration_id` | string | The ID of the configuration associated with this notification. | +| `run_url` | string | URL used to access the run UI page. | +| `run_id` | string | ID of the run which triggered this notification. | +| `run_message` | string | The reason the run was queued. | +| `run_created_at` | string | Timestamp of the run's creation. | +| `run_created_by` | string | Username of the user who created the run. | +| `workspace_id` | string | ID of the run's workspace. | +| `workspace_name` | string | Human-readable name of the run's workspace. | +| `organization_name` | string | Human-readable name of the run's organization. | +| `notifications` | array | List of events which caused this notification to be sent, with each event represented by an object. At present, this is always one event, but in the future HCP Terraform may roll up several notifications for a run into a single request. | +| `notifications[].message` | string | Human-readable reason for the notification. | +| `notifications[].trigger` | string | Value of the trigger which caused the notification to be sent. | +| `notifications[].run_status` | string | Status of the run at the time of notification. | +| `notifications[].run_updated_at` | string | Timestamp of the run's update. | +| `notifications[].run_updated_by` | string | Username of the user who caused the run to update. | + +#### Sample payload + +```json +{ + "payload_version": 1, + "notification_configuration_id": "nc-AeUQ2zfKZzW9TiGZ", + "run_url": "https://app.terraform.io/app/acme-org/my-workspace/runs/run-FwnENkvDnrpyFC7M", + "run_id": "run-FwnENkvDnrpyFC7M", + "run_message": "Add five new queue workers", + "run_created_at": "2019-01-25T18:34:00.000Z", + "run_created_by": "sample-user", + "workspace_id": "ws-XdeUVMWShTesDMME", + "workspace_name": "my-workspace", + "organization_name": "acme-org", + "notifications": [ + { + "message": "Run Canceled", + "trigger": "run:errored", + "run_status": "canceled", + "run_updated_at": "2019-01-25T18:37:04.000Z", + "run_updated_by": "sample-user" + } + ] +} +``` + +### Change request notification payload + +Change request events contain the following fields in their payloads. + +| Name | Type | Description | +| ------------------------------- | ------ | -------------------------------------------------------------- | +| `payload_version` | number | Always "1". | +| `notification_configuration_id` | string | The ID of the configuration associated with this notification. | +| `change_request_url` | string | URL used to access the change request UI page. | +| `change_request_subject` | string | title of the change request which triggered this notification. | +| `change_request_message` | string | The contents of the change request. | +| `change_request_created_at` | string | Timestamp of the change request's creation. | +| `change_request_created_by` | string | Username of the user who created the change_request. | +| `workspace_id` | string | ID of the run's workspace. | +| `workspace_name` | string | Human-readable name of the run's workspace. | +| `organization_name` | string | Human-readable name of the run's organization. | + +##### `Send a test` payload + +This is a sample payload you can send to test if notifications are working. The payload does not have a `run` or `workspace` context, resulting in null values. + +You can trigger a test notification from the workspace notification settings page. You can read more about verifying a [notification configuration](/terraform/enterprise/workspaces/settings/notifications#enabling-and-verifying-a-configuration). + +```json +{ + "payload_version": 1, + "notification_configuration_id": "nc-jWvVsmp5VxsaCeXm", + "run_url": null, + "run_id": null, + "run_message": null, + "run_created_at": null, + "run_created_by": null, + "workspace_id": null, + "workspace_name": null, + "organization_name": null, + "notifications": [ + { + "message": "Verification of test", + "trigger": "verification", + "run_status": null, + "run_updated_at": null, + "run_updated_by": null, + } + ] +} +``` + +### Workspace notification payload + +Workspace events include detailed information about workspace-level validation events like [health assessments](/terraform/enterprise/workspaces/health) if you enable them for the workspace. Much of the information provides details about the associated [assessment result](/terraform/enterprise/api-docs/assessment-results), which HCP Terraform uses to track instances of continuous validation. + +HCP Terraform returns different types of attributes returned in the payload details, depending on the type of `trigger_scope`. There are two main values for `trigger_scope`: `assessment` and `workspace`, examples of which you can see below. + +#### Health assessments + +Health assessment notifications for workspace events contain the following information: + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +| Name | Type | Description | +| ------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------- | +| `payload_version` | number | Always "2". | +| `notification_configuration_id` | string | The ID of the configuration associated with this notification. | +| `notification_configuration_url` | string | URL to get the notification configuration from the HCP Terraform API. | +| `trigger_scope` | string | Always "assessment" for workspace assessment notifications. | +| `trigger` | string | Value of the trigger that caused the notification to be sent. | +| `message` | string | Human-readable reason for the notification. | +| `details` | object | Object containing details specific to the notification. | +| `details.new_assessment_result` | object | The most recent assessment result. This result triggered the notification. | +| `details.new_assessment_result.id` | string | ID of the assessment result. | +| `details.new_assessment_result.url` | string | URL to get the assessment result from the HCP Terraform API. | +| `details.new_assessment_result.succeeded` | bool | Whether assessment succeeded. | +| `details.new_assessment_result.all_checks_succeeded` | bool | Whether all conditions passed. | +| `details.new_assessment_result.checks_passed` | number | The number of resources, data sources, and outputs passing their conditions. | +| `details.new_assessment_result.checks_failed` | number | The number of resources, data sources, and outputs with one or more failing conditions. | +| `details.new_assessment_result.checks_errored` | number | The number of resources, data sources, and outputs that had a condition error. | +| `details.new_assessment_result.checks_unknown` | number | The number of resources, data sources, and outputs that had conditions left unevaluated. | +| `details.new_assessment_result.drifted` | bool | Whether assessment detected drift. | +| `details.new_assessment_result.resources_drifted` | number | The number of resources whose configuration does not match from the workspace's state file. | +| `details.new_assessment_result.resources_undrifted` | number | The number of real resources whose configuration matches the workspace's state file. | +| `details.new_assessment_result.created_at` | string | Timestamp for when HCP Terraform created the assessment result. | +| `details.prior_assessment_result` | object | The assessment result immediately prior to the one that triggered the notification. | +| `details.prior_assessment_result.id` | string | ID of the assessment result. | +| `details.prior_assessment_result.url` | string | URL to get the assessment result from the HCP Terraform API. | +| `details.prior_assessment_result.succeeded` | bool | Whether assessment succeeded. | +| `details.prior_assessment_result.all_checks_succeeded` | bool | Whether all conditions passed. | +| `details.prior_assessment_result.checks_passed` | number | The number of resources, data sources, and outputs passing their conditions. | +| `details.prior_assessment_result.checks_failed` | number | The number of resources, data sources, and outputs with one or more failing conditions. | +| `details.prior_assessment_result.checks_errored` | number | The number of resources, data sources, and outputs that had a condition error. | +| `details.prior_assessment_result.checks_unknown` | number | The number of resources, data sources, and outputs that had conditions left unevaluated. | +| `details.prior_assessment_result.drifted` | bool | Whether assessment detected drift. | +| `details.prior_assessment_result.resources_drifted` | number | The number of resources whose configuration does not match the workspace's state file. | +| `details.prior_assessment_result.resources_undrifted` | number | The number of resources whose configuration matches the workspace's state file. | +| `details.prior_assessment_result.created_at` | string | Timestamp of the assessment result. | +| `details.workspace_id` | string | ID of the workspace that generated the notification. | +| `details.workspace_name` | string | Human-readable name of the workspace. | +| `details.organization_name` | string | Human-readable name of the organization. | + +##### Sample payload + +Health assessment payloads have information about resource drift and continuous validation checks. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "assessment", + "trigger": "assessment:drifted", + "message": "Drift Detected", + "details": { + "new_assessment_result": { + "id": "asmtres-vRVQxpqq64EA9V5a", + "url": "https://app.terraform.io/api/v2/assessment-results/asmtres-vRVQxpqq64EA9V5a", + "succeeded": true, + "drifted": true, + "all_checks_succeeded": true, + "resources_drifted": 4, + "resources_undrifted": 55, + "checks_passed": 33, + "checks_failed": 0, + "checks_errored": 0, + "checks_unknown": 0, + "created_at": "2022-06-09T05:23:10Z" + }, + "prior_assessment_result": { + "id": "asmtres-A6zEbpGArqP74fdL", + "url": "https://app.terraform.io/api/v2/assessment-results/asmtres-A6zEbpGArqP74fdL", + "succeeded": true, + "drifted": true, + "all_checks_succeeded": true, + "resources_drifted": 4, + "resources_undrifted": 55, + "checks_passed": 33, + "checks_failed": 0, + "checks_errored": 0, + "checks_unknown": 0, + "created_at": "2022-06-09T05:22:51Z" + }, + "workspace_id": "ws-XdeUVMWShTesDMME", + "workspace_name": "my-workspace", + "organization_name": "acme-org" + } +} +``` + +#### Automatic destroy runs + + + +@include 'tfc-package-callouts/ephemeral-workspaces.mdx' + + + +Automatic destroy run notifications for workspace events contain the following information: + +| Name | Type | Description | +| ---------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- | +| `payload_version` | string | Always 2. | +| `notification_configuration_id` | string | The ID of the notification's configuration. | +| `notification_configuration_url` | string | The URL to get the notification's configuration from the HCP Terraform API. | +| `trigger_scope` | string | Always "workspace" for ephemeral workspace notifications | +| `trigger` | string | Value of the trigger that caused HCP Terraform to send the notification. | +| `message` | string | Human-readable reason for the notification. | +| `details` | object | Object containing details specific to the notification. | +| `details.auto_destroy_at` | string | Timestamp when HCP Terraform will schedule the next destroy run. Only applies to reminder notifications. | +| `details.run_created_at` | string | Timestamp of when HCP Terraform successfully created a destroy run. Only applies to results notifications. | +| `details.run_status` | string | Status of the scheduled destroy run. Only applies to results notifications. | +| `details.run_external_id` | string | The ID of the scheduled destroy run. Only applies to results notifications. | +| `details.run_create_error_message` | string | Message detailing why the run was unable to be queued. Only applies to results notifications. | +| `details.trigger_type` | string | The type of notification, and the value is either "reminder" or "results". | +| `details.workspace_name` | string | Human-readable name of the workspace. | +| `details.organization_name` | string | Human-readable name of the organization. | + +##### Sample payload + +The shape of data in auto destroy notification payloads may differ depending on the success of the run HCP Terraform created. Refer to the specific examples below. + +###### Reminder + +Reminders that HCP Terraform will trigger a destroy run at some point in the future. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "workspace", + "trigger": "workspace:auto_destroy_reminder", + "message": "Auto Destroy Reminder", + "details": { + "auto_destroy_at": "2025-01-01T00:00:00Z", + "run_created_at": null, + "run_status": null, + "run_external_id": null, + "run_create_error_message": null, + "trigger_type": "reminder", + "workspace_name": "learned-english-dog", + "organization_name": "acme-org" + } +} +``` + +###### Results + +The final result of the scheduled auto destroy run includes additional metadata about the run. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "workspace", + "trigger": "workspace:auto_destroy_results", + "message": "Auto Destroy Results", + "details": { + "auto_destroy_at": null, + "run_created_at": "2022-06-09T05:22:51Z", + "run_status": "applied", + "run_external_id": "run-vRVQxpqq64EA9V5a", + "run_create_error_message": null, + "trigger_type": "results", + "workspace_name": "learned-english-dog", + "organization_name": "acme-org" + } +} +``` + +###### Failed run creation + +Run-specific values are empty when HCP Terraform was unable to create an auto destroy run. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "workspace", + "trigger": "workspace:auto_destroy_results", + "message": "Auto Destroy Results", + "details": { + "auto_destroy_at": null, + "run_created_at": null, + "run_status": null, + "run_external_id": null, + "run_create_error_message": "Configuration version is missing", + "trigger_type": "results", + "workspace_name": "learned-english-dog", + "organization_name": "acme-org" + } +} +``` + +## Notification authenticity + +If a `token` is configured, HCP Terraform provides an HMAC signature on all `"generic"` notification requests, using the `token` as the key. This is sent in the `X-TFE-Notification-Signature` header. The digest algorithm used is SHA-512. Notification target servers should verify the source of the HTTP request by computing the HMAC of the request body using the same shared secret, and dropping any requests with invalid signatures. + +Sample Ruby code for verifying the HMAC: + +```ruby +token = SecureRandom.hex +hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha512"), token, @request.body) +fail "Invalid HMAC" if hmac != @request.headers["X-TFE-Notification-Signature"] +``` + +## Notification verification and delivery responses + +When saving a configuration with `enabled` set to `true`, or when using the [verify API][], HCP Terraform sends a verification request to the configured URL. The response to this request is stored and available in the `delivery-responses` array of the `notification-configuration` resource. + +Configurations cannot be enabled if the verification request fails. Success is defined as an HTTP response with status code of `2xx`. +Configurations with `destination_type` `email` can only be verified manually, they do not require an HTTP response. + +The most recent response is stored in the `delivery-responses` array. + +Each delivery response has several fields: + +| Name | Type | Description | +| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `body` | string | Response body (may be truncated). | +| `code` | string | HTTP status code, e.g. `400`. | +| `headers` | object | All HTTP headers received, represented as an object with keys for each header name (lowercased) and an array of string values (most arrays will be size one). | +| `sent-at` | date | The UTC timestamp when the notification was sent. | +| `successful` | bool | Whether HCP Terraform considers this response to be successful. | +| `url` | string | The URL to which the request was sent. | + +[verify API]: #verify-a-notification-configuration + +## Create a notification configuration + +`POST /workspaces/:workspace_id/notification-configurations` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The ID of the workspace to list configurations for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully created a notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +If `enabled` is set to `true`, a verification request will be sent before saving the configuration. If this request receives no response or the response is not successful (HTTP 2xx), the configuration will not save. + +| Key path | Type | Default | Description | +| ---------------------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"notification-configuration"`. | +| `data.attributes.destination-type` | string | | Type of notification payload to send. Valid values are `"generic"`, `"email"`, `"slack"` or `"microsoft-teams"`. | +| `data.attributes.enabled` | bool | `false` | Disabled configurations will not send any notifications. | +| `data.attributes.name` | string | | Human-readable name for the configuration. | +| `data.attributes.token` | string or null | `null` | Optional write-only secure token, which can be used at the receiving server to verify request authenticity. See [Notification Authenticity][notification-authenticity] for more details. | +| `data.attributes.triggers` | array | `[]` | Array of triggers for which this configuration will send notifications. See [Notification Triggers][notification-triggers] for more details and a list of allowed values. | +| `data.attributes.url` | string | | HTTP or HTTPS URL to which notification requests will be made, only for configurations with `"destination_type:"` `"slack"`, `"microsoft-teams"` or `"generic"` | +| `data.relationships.users` | array | | Array of users part of the organization, only for configurations with `"destination_type:"` `"email"` | + +[notification-authenticity]: #notification-authenticity + +[notification-triggers]: #notification-triggers + +### Sample payload for generic notification configurations + +```json +{ + "data": { + "type": "notification-configuration", + "attributes": { + "destination-type": "generic", + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ] + } + } +} +``` + +### Sample payload for email notification configurations + +```json +{ + "data": { + "type": "notification-configurations", + "attributes": { + "destination-type": "email", + "enabled": true, + "name": "Notify organization users about run", + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ] + }, + "relationships": { + "users": { + "data": [ { "id": "organization-user-id", "type": "users" } ] + } + } + } +} +``` + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/notification-configurations +``` + +### Sample response + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +## List notification configurations + +Use the following endpoint to list all notification configurations for a workspace. + +`GET /workspaces/:workspace_id/notification-configurations` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list configurations from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. | + +### Query parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 notification configurations per page. | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/notification-configurations +``` + +### Sample response + +```json +{ + "data": [ + { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000000/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "run:errored", + "run:needs_attention" + ], + "delivery-responses": [], + "created-at": "2019-01-08T21:34:28.367Z", + "updated-at": "2019-01-08T21:34:28.367Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K" + } + }, + { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } + ] +} + +``` + +## Show a notification configuration + +`GET /notification-configurations/:notification-configuration-id` + +| Parameter | Description | +| -------------------------------- | ------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to show. | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ +``` + +### Sample response + +The `type` and `id` attributes in `relationships.subscribable` may also reference a `"teams"` and team ID, respectively. + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +## Update a notification configuration + +`PATCH /notification-configurations/:notification-configuration-id` + +| Parameter | Description | +| -------------------------------- | --------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to update. | + +If the `enabled` attribute is true, updating the configuration will cause HCP Terraform to send a verification request. If a response is received, it will be stored and returned in the `delivery-responses` attribute. More details in the [Notification Verification and Delivery Responses][] section above. + +[Notification Verification and Delivery Responses]: #notification-verification-and-delivery-responses + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully updated the notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | +| [404][] | [JSON API error object][] | Notification configuration not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +If `enabled` is set to `true`, a verification request will be sent before saving the configuration. If this request fails to send, or the response is not successful (HTTP 2xx), the configuration will not save. + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | (previous value) | Must be `"notification-configuration"`. | +| `data.attributes.enabled` | bool | (previous value) | Disabled configurations will not send any notifications. | +| `data.attributes.name` | string | (previous value) | User-readable name for the configuration. | +| `data.attributes.token` | string | (previous value) | Optional write-only secure token, which can be used at the receiving server to verify request authenticity. See [Notification Authenticity][notification-authenticity] for more details. | +| `data.attributes.triggers` | array | (previous value) | Array of triggers for sending notifications. See [Notification Triggers][notification-triggers] for more details. | +| `data.attributes.url` | string | (previous value) | HTTP or HTTPS URL to which notification requests will be made, only for configurations with `"destination_type:"` `"slack"`, `"microsoft-teams"` or `"generic"` | +| `data.relationships.users` | array | | Array of users part of the organization, only for configurations with `"destination_type:"` `"email"` | + +[notification-authenticity]: #notification-authenticity + +[notification-triggers]: #notification-triggers + +### Sample payload + +```json +{ + "data": { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000001/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "run:created", + "run:errored", + "run:needs_attention" + ], + } + } +} +``` + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K +``` + +### Sample response + +```json +{ + "data": { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000001/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "run:created", + "run:errored", + "run:needs_attention" + ], + "delivery-responses": [], + "created-at": "2019-01-08T21:34:28.367Z", + "updated-at": "2019-01-08T21:49:02.103Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K" + } + }, +} +``` + +## Verify a notification configuration + +`POST /notification-configurations/:notification-configuration-id/actions/verify` + +| Parameter | Description | +| -------------------------------- | --------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to verify. | + +This will cause HCP Terraform to send a verification request for the specified configuration. If a response is received, it will be stored and returned in the `delivery-responses` attribute. More details in the [Notification Verification and Delivery Responses][] section above. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | ---------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully verified the notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ/actions/verify +``` + +### Sample response + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +## Delete a notification configuration + +This endpoint deletes a notification configuration. + +`DELETE /notification-configurations/:notification-configuration-id` + +| Parameter | Description | +| -------------------------------- | --------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to delete. | + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------------------- | +| [204][] | None | Successfully deleted the notification configuration | +| [404][] | [JSON API error object][] | Notification configuration not found, or user unauthorized to perform action | + +### Sample request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ +``` + +## Team notification configuration + +Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs. + + + +@include 'tfc-package-callouts/notifications.mdx' + + + +### Create a team notification configuration + +By default, every team has a default email notification configuration with no users assigned. If a notification configuration has no users assigned, HCP Terraform sends email notifications to all team members. + +Use this endpoint to create a notification configuration to notify a team. + +`POST /teams/:team_id/notification-configurations` + +| Parameter | Description | +| ---------- | ------------------------------------------------- | +| `:team_id` | The ID of the team to create a configuration for. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully created a notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | +| [404][] | [JSON API error object][] | Team not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +#### Request body + +This `POST` endpoint requires a JSON object with the following properties as a request payload. Properties without a default value are required. + +If `enabled` is set to `true`, HCP Terraform sends a verification request before saving the configuration. If this request does not receive a response or the response is not successful (HTTP 2xx), the configuration will not be saved. + +| Key path | Type | Default | Description | +| ----------------------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"notification-configuration"`. | +| `data.attributes.destination-type` | string | | Type of notification payload to send. Valid values are `"generic"`, `"email"`, `"slack"` or `"microsoft-teams"`. | +| `data.attributes.enabled` | bool | `false` | Disabled configurations will not send any notifications. | +| `data.attributes.name` | string | | Human-readable name for the configuration. | +| `data.attributes.token` | string or null | `null` | Optional write-only secure token, which can be used at the receiving server to verify request authenticity. See [Notification Authenticity][notification-authenticity] for more details. | +| `data.attributes.triggers` | array | `[]` | Array of triggers for which this configuration will send notifications. See [Notification Triggers][notification-triggers] for more details and a list of allowed values. | +| `data.attributes.url` | string | | HTTP or HTTPS URL to which notification requests will be made, only for configurations with `"destination_type:"` `"slack"`, `"microsoft-teams"` or `"generic"` | +| `data.attributes.email_all_members` | bool | | Email all team members, only for configurations with `"destination_type:" "email"`. | +| `data.relationships.users` | array | | Array of users part of the organization, only for configurations with `"destination_type:"` `"email"` | + +[notification-authenticity]: #notification-authenticity + +[notification-triggers]: #notification-triggers + +#### Sample payload for generic notification configurations + +```json +{ + "data": { + "type": "notification-configuration", + "attributes": { + "destination-type": "generic", + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "triggers": [ + "change_request:created" + ] + } + } +} +``` + +#### Sample payload for email notification configurations + +```json +{ + "data": { + "type": "notification-configurations", + "attributes": { + "destination-type": "email", + "enabled": true, + "name": "Email teams about change requests", + "triggers": [ + "change_request:created" + ] + }, + "relationships": { + "users": { + "data": [ { "id": "organization-user-id", "type": "users" } ] + } + } + } +} +``` + +#### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC/notification-configurations +``` + +#### Sample response + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "change_request:created" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2024 21:34:37 GMT" + ] + }, + "sent-at": "2024-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2024-01-08T21:32:14.125Z", + "updated-at": "2024-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "team-6p5jTwJQXwqZBncC", + "type": "teams" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +### List team notification configurations + +Use this endpoint to list notification configurations for a team. + +`GET /teams/:team_id/notification-configurations` + +| Parameter | Description | +| ---------- | ------------------------------------------------ | +| `:team_id` | The ID of the teams to list configurations from. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 notification configurations per page. | + +#### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC/notification-configurations +``` + +#### Sample response + +```json +{ + "data": [ + { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000000/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "change_request:created" + ], + "delivery-responses": [], + "created-at": "2019-01-08T21:34:28.367Z", + "updated-at": "2019-01-08T21:34:28.367Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "team-TdeUVMWShTesDMME", + "type": "teams" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K" + } + }, + { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "change_request:created" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "team-XdeUVMWShTesDMME", + "type": "teams" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } + ] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/oauth-clients.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/oauth-clients.mdx new file mode 100644 index 0000000000..c16d5161c7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/oauth-clients.mdx @@ -0,0 +1,603 @@ +--- +page_title: /oauth-clients API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/oauth-clients` endpoint to manage + connections between VCS providers and organizations and projects. Learn how to + read, create, update, and destroy clients. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# OAuth client API reference + +An OAuth client represents the connection between an organization and a VCS provider. By default, you can globally access an OAuth client throughout the organization, or you can have scope access to one or more [projects](/terraform/enterprise/projects/manage). + +## List OAuth Clients + +`GET /organizations/:organization_name/oauth-clients` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:organization_name` | The name of the organization. | + +This endpoint allows you to list VCS connections between an organization and a VCS provider (GitHub, Bitbucket, or GitLab) for use when creating or setting up workspaces. + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ---------------------- | +| [200][] | [JSON API document][] (`type: "oauth-clients"`) | Success | +| [404][] | [JSON API error object][] | Organization not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 oauth clients per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/oauth-clients +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckpK", + "type": "agent-pools" + }, + "links": { + "related": "/api/v2/agent-pools/apool-VsmjEMcYkShrckpK" + } + } + } + } + ] +} +``` + +## Show an OAuth Client + +`GET /oauth-clients/:id` + +| Parameter | Description | +| --------- | ---------------------------------- | +| `:id` | The ID of the OAuth Client to show | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-clients"`) | Success | +| [404][] | [JSON API error object][] | OAuth Client not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K +``` + +### Sample Response + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckpK", + "type": "agent-pools" + }, + "links": { + "related": "/api/v2/agent-pools/apool-VsmjEMcYkShrckpK" + } + } + } + } +} +``` + +## Create an OAuth Client + +`POST /organizations/:organization_name/oauth-clients` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization that will be connected to the VCS provider. The organization must already exist in the system, and the user must have permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint allows you to create a VCS connection between an organization and a VCS provider (GitHub or GitLab) for use when creating or setting up workspaces. By using this API endpoint, you can provide a pre-generated OAuth token string instead of going through the process of creating a GitHub or GitLab OAuth Application. + +To learn how to generate one of these token strings for your VCS provider, you can read the following documentation: + +- [GitHub and GitHub Enterprise](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) +- [GitLab, GitLab Community Edition, and GitLab Enterprise Edition](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token) +- [Azure DevOps Server](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops-2019&tabs=preview-page) + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "oauth-clients"`) | OAuth Client successfully created | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"oauth-clients"`. | +| `data.attributes.service-provider` | string | | The VCS provider being connected with. Valid options are `"github"`, `"github_enterprise"`, `"gitlab_hosted"`, `"gitlab_community_edition"`, `"gitlab_enterprise_edition"`, or `"ado_server"`. | +| `data.attributes.name` | string | `null` | An optional display name for the OAuth Client. If left `null`, the UI will default to the display name of the VCS provider. | +| `data.attributes.key` | string | | The OAuth Client key. It can refer to a Consumer Key, Application Key, or another type of client key for the VCS provider. | +| `data.attributes.http-url` | string | | The homepage of your VCS provider (e.g. `"https://github.com"` or `"https://ghe.example.com"` or `"https://gitlab.com"`). | +| `data.attributes.api-url` | string | | The base URL as per your VCS provider's API documentation (e.g. `"https://api.github.com"`, `"https://ghe.example.com/api/v3"` or `"https://gitlab.com/api/v4"`). | +| `data.attributes.oauth-token-string` | string | | The token string you were given by your VCS provider | +| `data.attributes.private-key` | string | | **Required for Azure DevOps Server. Not used for any other providers.** The text of the SSH private key associated with your Azure DevOps Server account. | +| `data.attributes.secret` | string | | The OAuth client secret. For Bitbucket Data Center, the secret is the text of the SSH private key associated with your Bitbucket Data Center application link. | +| `data.attributes.rsa-public-key` | string | | **Required for Bitbucket Data Center in conjunction with the `secret`. Not used for any other providers.** The text of the SSH public key associated with your Bitbucket Data Center application link. | +| `data.attributes.organization-scoped` | boolean | | Whether or not the OAuth client is scoped to all projects and workspaces in the organization. Defaults to `true`. | +| `data.relationships.projects.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects are associated with the OAuth client. If `data.attributes.organization-scoped` is set to `false`, the OAuth client is only available to this list of projects. Each object in this list must contain a project `id` and use the `"projects"` type. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. | +| `data.relationships.agent-pool.data` | object | `{}` | The Agent Pool associated to the VCS connection. This pool will be responsible for forwarding VCS Provider API calls and cloning VCS repositories. | + +### Sample Payload + +```json +{ + "data": { + "type": "oauth-clients", + "attributes": { + "service-provider": "github", + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "oauth-token-string": "4306823352f0009d0ed81f1b654ac17a", + "organization-scoped": false + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/oauth-clients +``` + +### Sample Response + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +## Update an OAuth Client + +`PATCH /oauth-clients/:id` + +| Parameter | Description | +| --------- | ------------------------------------- | +| `:id` | The ID of the OAuth Client to update. | + +Use caution when changing attributes with this endpoint; editing an OAuth client that workspaces are currently using can have unexpected effects. + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-clients"`) | The request was successful | +| [404][] | [JSON API error object][] | OAuth Client not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------------------------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"oauth-clients"`. | +| `data.attributes.name` | string | (previous value) | An optional display name for the OAuth Client. If set to `null`, the UI will default to the display name of the VCS provider. | +| `data.attributes.key` | string | (previous value) | The OAuth Client key. It can refer to a Consumer Key, Application Key, or another type of client key for the VCS provider. | +| `data.attributes.secret` | string | (previous value) | The OAuth client secret. For Bitbucket Data Center, this secret is the text of the SSH private key associated with your Bitbucket Data Center application link. | +| `data.attributes.rsa-public-key` | string | (previous value) | **Required for Bitbucket Data Center in conjunction with the `secret`. Not used for any other providers.** The text of the SSH public key associated with your Bitbucket Data Center application link. | +| `data.attributes.organization-scoped` | boolean | (previous value) | Whether or not the OAuth client is available to all projects and workspaces in the organization. | +| `data.relationships.projects` | array\[object] | (previous value) | A list of resource identifier objects that defines which projects are associated with the OAuth client. If `data.attributes.organization-scoped` is set to `false`, the OAuth client is only available to this list of projects. Each object in this list must contain a project `id` and use the `"projects"` type. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. Sending an empty array clears all project assignments. | +| `data.relationships.agent-pool.data` | object | `{}` | The Agent Pool associated to the VCS connection. This pool will be responsible for forwarding VCS Provider API calls and cloning VCS repositories. | + +### Sample Payload + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "key": "key", + "secret": "secret", + "organization-scoped": false + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K +``` + +### Sample Response + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +## Destroy an OAuth Client + +`DELETE /oauth-clients/:id` + +| Parameter | Description | +| --------- | ------------------------------------- | +| `:id` | The ID of the OAuth Client to destroy | + +This endpoint allows you to remove an existing connection between an organization and a VCS provider (GitHub, Bitbucket, or GitLab). + +**Note:** Removing the OAuth Client will unlink workspaces that use this connection from their repositories, and these workspaces will need to be manually linked to another repository. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------ | +| [204][] | Empty response | The OAuth Client was successfully destroyed | +| [404][] | [JSON API error object][] | Organization or OAuth Client not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K +``` + +## Attach to a project + +`POST /oauth-clients/:id/relationships/projects` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the OAuth client to attach to a project. Use the [List OAuth Clients](#list-oauth-clients) endpoint to reference your OAuth client IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | OAuth Client not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects to attach the OAuth client to. These objects must contain `id` and `type` properties, and the `type` property must be `projects` (e.g. `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K/relationships/projects +``` + +## Detach an OAuth Client from projects + +`DELETE /oauth-clients/:id/relationships/projects` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the oauth client you want to detach from the specified projects. Use the "List OAuth Clients" endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | OAuth Client not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects are associated with the OAuth client. If `data.attributes.organization-scoped` is set to `false`, the OAuth client is only available to this list of projects. Each object in this list must contain a project `id` and use the `"projects"` type. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K/relationships/projects +``` + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| -------------- | --------------------------------------- | +| `oauth_tokens` | The OAuth tokens managed by this client | +| `projects` | The projects scoped to this client | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/oauth-tokens.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/oauth-tokens.mdx new file mode 100644 index 0000000000..83cdaaae1b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/oauth-tokens.mdx @@ -0,0 +1,264 @@ +--- +page_title: /oauth-tokens API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/oauth-tokens` endpoint to manage the + OAuth tokens that connect workspaces to VCS providers. Learn how to read, + update, and destroy tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# OAuth token API reference + +The `oauth-token` object represents a VCS configuration which includes the OAuth connection and the associated OAuth token. This object is used when creating a workspace to identify which VCS connection to use. + +## List OAuth Tokens + +List all the OAuth Tokens for a given OAuth Client + +`GET /oauth-clients/:oauth_client_id/oauth-tokens` + +| Parameter | Description | +| ------------------ | -------------------------- | +| `:oauth_client_id` | The ID of the OAuth Client | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-tokens"`) | Success | +| [404][] | [JSON API error object][] | OAuth Client not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ---------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 oauth tokens per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/oauth-clients/oc-GhHqb5rkeK19mLB8/oauth-tokens +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ot-hmAyP66qk2AMVdbJ", + "type": "oauth-tokens", + "attributes": { + "created-at":"2017-11-02T06:37:49.284Z", + "service-provider-user":"skierkowski", + "has-ssh-key": false + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-GhHqb5rkeK19mLB8", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-GhHqb5rkeK19mLB8" + } + } + }, + "links": { + "self": "/api/v2/oauth-tokens/ot-hmAyP66qk2AMVdbJ" + } + } + ] +} +``` + +## Show an OAuth Token + +`GET /oauth-tokens/:id` + +| Parameter | Description | +| --------- | --------------------------------- | +| `:id` | The ID of the OAuth token to show | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-tokens"`) | Success | +| [404][] | [JSON API error object][] | OAuth Token not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL +``` + +### Sample Response + +```json +{ + "data": { + "id": "ot-29t7xkUKiNC2XasL", + "type": "oauth-tokens", + "attributes": { + "created-at": "2018-08-29T14:07:22.144Z", + "service-provider-user": "EM26Jj0ikRsIFFh3fE5C", + "has-ssh-key": false + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-WMipGbuW8q7xCRmJ", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-WMipGbuW8q7xCRmJ" + } + } + }, + "links": { + "self": "/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL" + } + } +} +``` + +## Update an OAuth Token + +`PATCH /oauth-tokens/:id` + +| Parameter | Description | +| --------- | ----------------------------------- | +| `:id` | The ID of the OAuth token to update | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-tokens"`) | OAuth Token successfully updated | +| [404][] | [JSON API error object][] | OAuth Token not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------- | ------ | ------- | ------------------------- | +| `data.type` | string | | Must be `"oauth-tokens"`. | +| `data.attributes.ssh-key` | string | | **Optional.** The SSH key | + +### Sample Payload + +```json +{ + "data": { + "id": "ot-29t7xkUKiNC2XasL", + "type": "oauth-tokens", + "attributes": { + "ssh-key": "..." + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL +``` + +### Sample Response + +```json +{ + "data": { + "id": "ot-29t7xkUKiNC2XasL", + "type": "oauth-tokens", + "attributes": { + "created-at": "2018-08-29T14:07:22.144Z", + "service-provider-user": "EM26Jj0ikRsIFFh3fE5C", + "has-ssh-key": false + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-WMipGbuW8q7xCRmJ", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-WMipGbuW8q7xCRmJ" + } + } + }, + "links": { + "self": "/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL" + } + } +} +``` + +## Destroy an OAuth Token + +`DELETE /oauth-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------------------ | +| `:id` | The ID of the OAuth Token to destroy | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | Empty response | The OAuth Token was successfully destroyed | +| [404][] | [JSON API error object][] | OAuth Token not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-memberships.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-memberships.mdx new file mode 100644 index 0000000000..dec59d2968 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-memberships.mdx @@ -0,0 +1,497 @@ +--- +page_title: /organization-memberships API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/organization-memberships` endpoint to + manage membership in an organization. Invite, list, and remove members from + organizations. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organization memberships API reference + +Users are added to organizations by inviting them to join. Once accepted, they become members of the organization. The Organization Membership resource represents this membership. + +You can invite users who already have an account, as well as new users. If the user has an existing account with the same email address used to invite them, they can reuse the same login. + +-> **Note:** Once a user is a member of the organization, you can manage their team memberships using [the Team Membership API](/terraform/enterprise/api-docs/team-members). + +## Invite a User to an Organization + +`POST /organizations/:organization_name/organization-memberships` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the user will be invited to join. The inviting user must have permission to manage organization memberships. | + +-> **Note:** Organization membership management is restricted to members of the owners team, the owners [team API token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens), the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens), and users or teams with one of the [Team Management](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions) permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] | Successfully invited the user | +| [400][] | [JSON API error object][] | Unable to invite user due to organization limits | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Unable to invite user due to validation errors | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"organization-memberships"`. | +| `data.attributes.email` | string | | The email address of the user to be invited. | +| `data.relationships.teams.data[]` | array\[object] | | A list of resource identifier objects that defines which teams the invited user will be a member of. These objects must contain `id` and `type` properties, and the `type` property must be `teams` (e.g. `{ "id": "team-GeLZkdnK6xAVjA5H", "type": "teams" }`). Obtain team IDs from the [List Teams](/terraform/enterprise/api-docs/teams#list-teams) endpoint. All users must be added to at least one team. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "email": "test@example.com" + }, + "relationships": { + "teams": { + "data": [ + { + "type": "teams", + "id": "team-GeLZkdnK6xAVjA5H" + } + ] + } + }, + "type": "organization-memberships" + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships +``` + +### Sample Response + +```json +{ + "data": { + "id": "ou-nX7inDHhmC3quYgy", + "type": "organization-memberships", + "attributes": { + "status": "invited" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-GeLZkdnK6xAVjA5H", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-J8oxGmRk5eC2WLfX", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + "included": [ + { + "id": "user-J8oxGmRk5eC2WLfX", + "type": "users", + "attributes": { + "username": null, + "is-service-account": false, + "auth-method": "hcp_sso", + "avatar-url": "https://www.gravatar.com/avatar/55502f40dc8b7c769880b10874abc9d0?s=100&d=mm", + "two-factor": { + "enabled": false, + "verified": false + }, + "email": "test@example.com", + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true, + "can-manage-user-tokens": false + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-J8oxGmRk5eC2WLfX/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-J8oxGmRk5eC2WLfX" + } + } + ] +} +``` + +## List Memberships for an Organization + +`GET /organizations/:organization_name/organization-memberships` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------- | +| `:organization_name` | The name of the organization to list the memberships of. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Organization memberships are searchable by user name and email. | +| `filter[status]` | **Optional.** If specified, restricts results to those with the matching status value. Valid values are `invited` and `active`. | +| `filter[email]` | **Optional.** If specified, restricts results to those with a matching user email address. If multiple comma separated values are specified, results matching any of the values are returned. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 users per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ou-tTJph1AQVK5ZmdND", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-vaQqszES9JnuK4eB", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "ou-D6HPYFt4GzeBt3gB", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-oqCgH7NgTn95jTGc", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "ou-x1E2eBwYwusLDC7h", + "type": "organization-memberships", + "attributes": { + "status": "invited" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-UntUdBTHsVRQMzC8", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "status-counts": { + "total": 3, + "active": 2, + "invited": 1 + }, + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 3 + } + } +} +``` + +## List User's Own Memberships + +`GET /organization-memberships` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organization-memberships +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ou-VgJgfbDVN3APUm2F", + "type": "organization-memberships", + "attributes": { + "status": "invited" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-4QrJKzxB3J5N4cJc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-vaQqszES9JnuK4eB", + "type": "users" + } + }, + "organization": { + "data": { + "id": "acme-corp", + "type": "organizations" + } + } + } + }, + { + "id": "ou-tTJph1AQVK5ZmdND", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-vaQqszES9JnuK4eB", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ] +} +``` + +## Show a Membership + +`GET /organization-memberships/:organization_membership_id` + +| Parameter | Description | +| ----------------------------- | --------------------------- | +| `:organization_membership_id` | The organization membership | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organization-memberships"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization membership not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organization-memberships/ou-kit6GaMo3zPGCzWb +``` + +### Sample Response + +```json +{ + "data": { + "id": "ou-kit6GaMo3zPGCzWb", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-97LkM7QciNkwb2nh", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-hn6v2WK1naDpGadd", + "type": "users" + } + }, + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` + +## Remove User from Organization + +`DELETE /organization-memberships/:organization_membership_id` + +| Parameter | Description | +| ----------------------------- | --------------------------- | +| `:organization_membership_id` | The organization membership | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------------------- | +| [204][] | Empty body | Successfully removed the user from the organization | +| [403][] | [JSON API error object][] | Unable to remove the user: you cannot remove yourself from organizations which you own | +| [404][] | [JSON API error object][] | Organization membership not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organization-memberships/ou-tTJph1AQVK5ZmdND +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `user` - The user associated with the membership. +- `teams` - Teams the user is a member of. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-tags.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-tags.mdx new file mode 100644 index 0000000000..bcebf92fbc --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-tags.mdx @@ -0,0 +1,230 @@ +--- +page_title: /tags API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's organization `/tags` endpoint to assign, + list, and delete tags for an organization. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organization tags API reference + +This API returns the list of tags used in workspaces across the organization. Tags can be added to this pool via workspaces. Tags deleted here will be removed from all other workspaces. Tags can be added, applied, removed and deleted in bulk. + +Tags are subject to the following rules: + +- Workspace tags or tags must be one or more characters, have a 255 character limit, and can include letters, numbers, colons, hyphens, and underscores. +- You can create tags for a workspace using the user interface or the API. After you create a tag, you can assign it to other workspaces in the same organization. +- You cannot create tags for a workspace using the CLI. +- You cannot set tags at the project level, so there is no tag inheritance from projects to workspaces. + +## List Tags + +`GET /organizations/:organization_name/tags` + +| Parameter | Description | +| -------------------- | ---------------------------------------------- | +| `:organization_name` | The name of the organization to list tags from | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------------------- | ---------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Organization tags are searchable by name likeness. | +| `filter[exclude][taggable][id]` | **Optional.** If specified, omits organization's related workspace's tags. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 organization tags per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/tags +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tag-1", + "type": "tags", + "attributes": { + "name": "tag1", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 1 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "tag-2", + "type": "tags", + "attributes": { + "name": "tag2", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ] +} +``` + +## Delete tags + +This endpoint deletes one or more tags from an organization. The organization and tags must already +exist. Tags deleted here will be removed from all other resources. + +`DELETE /organizations/:organization_name/tags` + +| Parameter | Description | +| -------------------- | ------------------------------------------------ | +| `:organization_name` | The name of the organization to delete tags from | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [204][] | No Content | Successfully removed tags from organization | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that `type` and `id` are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ---------------------------- | +| `data[].type` | string | | Must be `"tags"`. | +| `data[].id` | string | | The id of the tag to remove. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tags", + "id": "tag-Yfha4YpPievQ8wJw" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/hashicorp/tags +``` + +## Sample Response + +No response body. + +Status code `204`. + +## Add workspaces to a tag + +`POST /tags/:tag_id/relationships/workspaces` + +| Parameter | Description | +| --------- | ---------------------------------------------------- | +| `:tag_id` | The ID of the tag that workspaces should have added. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------- | +| [204][] | No Content | Successfully added workspaces to tag | +| [404][] | [JSON API error object][] | Tag not found, or user unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------------- | +| `data[].type` | string | | Must be `"workspaces"`. | +| `data[].id` | string | | The id of the workspace to add. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/tags/tag-2/relationships/workspaces +``` + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-pmKTbUwH2VPiiTC4" + } + ] +} +``` + +### Sample Response + +No response body. + +Status code `204`. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-tokens.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-tokens.mdx new file mode 100644 index 0000000000..75894a177c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organization-tokens.mdx @@ -0,0 +1,148 @@ +--- +page_title: /organizations/authentication-token API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/organizations/authentication-token` + endpoint to generate and delete organization-level API tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organization tokens API reference + +## Generate a new organization token + +`POST /organizations/:organization_name/authentication-token` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------- | +| `:organization_name` | The name of the organization to generate a token for. | + +Generates a new [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens), replacing any existing token. + +Only members of the owners team, the owners [team API token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens), and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) can access this endpoint. + +This endpoint returns the secret text of the new authentication token. You can only access this token when you create it and can not recover it later. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------- | +| [201][] | [JSON API document][] (`type: "authentication-tokens"`) | Success | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ---------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"authentication-token"`. | +| `data.attributes.expired-at` | string | `null` | The UTC date and time that the Organization Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | + +### Sample Payload + +```json +{ + "data": { + "type": "authentication-token", + "attributes": { + "expired-at": "2023-04-06T12:00:00.000Z" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/authentication-token +``` + +### Sample Response + +```json +{ + "data": { + "id": "4111756", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:11:28.075Z", + "last-used-at": null, + "description": null, + "token": "ZgqYdzuvlv8Iyg.atlasv1.6nV7t1OyFls341jo1xdZTP72fN0uu9VL55ozqzekfmToGFbhoFvvygIRy2mwVAXomOE", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-62goNpx1ThQf689e", + "type": "users" + } + } + } + } +} +``` + +## Delete the organization token + +`DELETE /organizations/:organization/authentication-token` + +| Parameter | Description | +| -------------------- | --------------------------------------------- | +| `:organization_name` | Which organization's token should be deleted. | + +Only members of the owners team, the owners [team API token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens), and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) can access this endpoint. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------- | +| [204][] | No Content | Success | +| [404][] | [JSON API error object][] | User not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/authentication-token +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organizations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organizations.mdx new file mode 100644 index 0000000000..186f708b53 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/organizations.mdx @@ -0,0 +1,986 @@ +--- +page_title: /organizations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/organizations` endpoint to create, + update, and destroy organizations, and read their entitlement sets, module + producers, and data retention policies. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organizations API reference + +The Organizations API is used to list, show, create, update, and destroy organizations. + +## List Organizations + +`GET /organizations` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +Currently, this endpoint returns a full, unpaginated list of organizations (without pagination metadata) if both of the pagination query parameters are omitted. To avoid inconsistent behavior, we recommend always supplying pagination parameters when building against this API. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Organizations are searchable by name and notification email. This query takes precedence over the attribute specific searches `q[email]` or `q[name]`. | +| `q[email]` | **Optional.** A search query string. This query searches organizations by notification email. If used with `q[name]`, it returns organizations that match both queries. | +| `q[name]` | **Optional.** A search query string. This query searches organizations by name. If used with `q[email]`, it returns organizations that match both queries. | +| `page[number]` | **Optional.** Defaults to the first page, if omitted when `page[size]` is provided. | +| `page[size]` | **Optional.** Defaults to 20 organizations per page, if omitted when `page[number]` is provided. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations\?page\[number\]\=1\&page\[size\]\=20 +``` + +### Sample Response + +**Note:** Only HCP Terraform organizations return the `two-factor-conformant` and `assessments-enforced` properties. + +```json +{ + "data": [ + { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-Hysjx5eUviuKVCJY", + "created-at": "2021-08-24T23:10:04.675Z", + "email": "hashicorp@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "plan-identifier": "developer", + "cost-estimation-enabled": true, + "send-passing-statuses-for-untriggered-speculative-plans": true, + "aggregated-commit-status-enabled": false, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": true, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": true, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": true, + "can-update-oauth": true, + "can-update-sentinel": true, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": true, + "can-manage-tags": true, + "can-manage-varsets": true, + "can-read-varsets": true, + "can-manage-public-providers": true, + "can-create-provider": true, + "can-manage-public-modules": true, + "can-manage-custom-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-Hysjx5eUviuKVCJY", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + }, + { + "id": "hashicorp-two", + "type": "organizations", + "attributes": { + "external-id": "org-iJ5tr4WgB4WpA1hD", + "created-at": "2022-01-04T18:57:16.036Z", + "email": "hashicorp@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "plan-identifier": "free", + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": false, + "name": "hashicorp-two", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-varsets": true, + "can-read-varsets": true, + "can-manage-public-providers": true, + "can-create-provider": true, + "can-manage-public-modules": true, + "can-manage-custom-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-project": false + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp-two/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp-two/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-iJ5tr4WgB4WpA1hD", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp-two/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp-two/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp-two" + } + } + ], + "links": { + "self": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show an Organization + +`GET /organizations/:organization_name` + +| Parameter | Description | +| -------------------- | ------------------------------------ | +| `:organization_name` | The name of the organization to show | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/hashicorp +``` + +### Sample Response + +**Note:** Only HCP Terraform organizations return the `two-factor-conformant` and `assessments-enforced` properties. + +```json +{ + "data": { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-WV6DfwfxxXvLfvfs", + "created-at": "2020-03-26T22:13:38.456Z", + "email": "user@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": false, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-public-modules": true, + "can-manage-public-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-provider": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-WV6DfwfxxXvLfvfs", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + } +} +``` + +## Create an Organization + +`POST /organizations` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "organizations"`) | The organization was successfully created | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------- | ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"organizations"` | +| `data.attributes.name` | string | | Name of the organization | +| `data.attributes.email` | string | | Admin email address | +| `data.attributes.session-timeout` | integer | 20160 | Session timeout after inactivity (minutes) | +| `data.attributes.session-remember` | integer | 20160 | Session expiration (minutes) | +| `data.attributes.collaborator-auth-policy` | string | password | Authentication policy (`password` or `two_factor_mandatory`) | +| `data.attributes.cost-estimation-enabled` | boolean | false | Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to false. In Terraform Enterprise, you must also enable cost estimation in [Site Administration](/terraform/enterprise/admin/application/integration#cost-estimation-integration). | +| `data.attributes.send-passing-statuses-for-untriggered-speculative-plans` | boolean | false | Whether or not to send VCS status updates for untriggered speculative plans. This can be useful if large numbers of untriggered workspaces are exhausting request limits for connected version control service providers like GitHub. Defaults to false. In Terraform Enterprise, this setting is always false and cannot be changed but is also available in Site Administration. | +| `data.attributes.aggregated-commit-status-enabled` | boolean | true | Whether or not to aggregate VCS status updates for triggered workspaces. This is useful for monorepo projects with configuration spanning many workspaces. Defaults to `true`. You cannot use this option if `send-passing-statuses-for-untriggered-speculative-plans` is set to `true`. | +| `data.attributes.speculative-plan-management-enabled` | boolean | true | Whether or not to enable [Automatically cancel plan-only runs](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management). Defaults to `true`. | +| `data.attributes.owners-team-saml-role-id` | string | (nothing) | **Optional.** **SAML only** The name of the ["owners" team](/terraform/enterprise/saml/team-membership#managing-membership-of-the-owners-team) | +| `data.attributes.assessments-enforced` | boolean | (false) | Whether or not to compel health assessments for all eligible workspaces. When true, health assessments occur on all compatible workspaces, regardless of the value of the workspace setting `assessments-enabled`. When false, health assessments only occur for workspaces that opt in by setting `assessments-enabled: true`. | +| `data.attributes.allow-force-delete-workspaces` | boolean | (false) | Whether workspace administrators can [delete workspaces with resources under management](/terraform/enterprise/users-teams-organizations/organizations#general). If false, only organization owners may delete these workspaces. | +| `data.attributes.default-execution-mode` | boolean | `remote` | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use by default. Valid values are `remote`, `local`, and `agent`. | +| `data.attributes.default-agent-pool-id` | string | (previous value) | Required when `default-execution-mode` is set to `agent`. The ID of the agent pool belonging to the organization. Do _not_ specify this value if you set `execution-mode` to `remote` or `local`. | + +### Sample Payload + +```json +{ + "data": { + "type": "organizations", + "attributes": { + "name": "hashicorp", + "email": "user@example.com" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations +``` + +### Sample Response + +**Note:** Only HCP Terraform organizations return the `two-factor-conformant` and `assessments-enforced` properties. + +```json +{ + "data": { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-Bzyc2JuegvVLAibn", + "created-at": "2021-08-30T18:09:57.561Z", + "email": "user@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": false, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-public-modules": true, + "can-manage-public-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-provider": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + }, + "included": [ + { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets", + "attributes": { + "agents": false, + "audit-logging": false, + "configuration-designer": true, + "cost-estimation": false, + "global-run-tasks": false, + "module-tests-generation": false, + "operations": true, + "policy-enforcement": false, + "policy-limit": null, + "policy-mandatory-enforcement-limit": null, + "policy-set-limit": null, + "private-module-registry": true, + "run-task-limit": null, + "run-task-mandatory-enforcement-limit": null, + "run-task-workspace-limit": null, + "run-tasks": false, + "self-serve-billing": true, + "sentinel": false, + "sso": false, + "state-storage": true, + "teams": false, + "usage-reporting": false, + "user-limit": 5, + "vcs-integrations": true, + "versioned-policy-set-limit": null + }, + "links": { + "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn" + } + } + ] +} +``` + +## Update an Organization + +`PATCH /organizations/:organization_name` + +| Parameter | Description | +| -------------------- | -------------------------------------- | +| `:organization_name` | The name of the organization to update | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The organization was successfully updated | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------- | ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"organizations"` | +| `data.attributes.name` | string | | Name of the organization | +| `data.attributes.email` | string | | Admin email address | +| `data.attributes.session-timeout` | integer | 20160 | Session timeout after inactivity (minutes) | +| `data.attributes.session-remember` | integer | 20160 | Session expiration (minutes) | +| `data.attributes.collaborator-auth-policy` | string | password | Authentication policy (`password` or `two_factor_mandatory`) | +| `data.attributes.cost-estimation-enabled` | boolean | false | Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to false. In Terraform Enterprise, you must also enable cost estimation in [Site Administration](/terraform/enterprise/admin/application/integration#cost-estimation-integration). | +| `data.attributes.send-passing-statuses-for-untriggered-speculative-plans` | boolean | false | Whether or not to send VCS status updates for untriggered speculative plans. This can be useful if large numbers of untriggered workspaces are exhausting request limits for connected version control service providers like GitHub. Defaults to false. In Terraform Enterprise, this setting is always false and cannot be changed but is also available in Site Administration. | +| `data.attributes.aggregated-commit-status-enabled` | boolean | true | Whether or not to aggregate VCS status updates for triggered workspaces. This is useful for monorepo projects with configuration spanning many workspaces. Defaults to `true`. You cannot use this option if `send-passing-statuses-for-untriggered-speculative-plans` is set to `true`. | +| `data.attributes.speculative-plan-management-enabled` | boolean | true | Whether or not to enable [Automatically cancel plan-only runs](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management). Defaults to `true`. | +| `data.attributes.owners-team-saml-role-id` | string | (nothing) | **Optional.** **SAML only** The name of the ["owners" team](/terraform/enterprise/saml/team-membership#managing-membership-of-the-owners-team) | +| `data.attributes.assessments-enforced` | boolean | false | Whether or not to compel health assessments for all eligible workspaces. When true, health assessments occur on all compatible workspaces, regardless of the value of the workspace setting `assessments-enabled`. When false, health assessments only occur for workspaces that opt in by setting `assessments-enabled: true`. | +| `data.attributes.allow-force-delete-workspaces` | boolean | false | Whether workspace administrators can [delete workspaces with resources under management](/terraform/enterprise/users-teams-organizations/organizations#general). If false, only organization owners may delete these workspaces. | +| `data.attributes.default-execution-mode` | boolean | `remote` | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use by default. Valid values are `remote`, `local`, and `agent`. | +| `data.attributes.default-agent-pool-id` | string | (previous value) | Required when `default-execution-mode` is set to `agent`. The ID of the agent pool belonging to the organization. Do _not_ specify this value if you set `execution-mode` to `remote` or `local`. | + +### Sample Payload + +```json +{ + "data": { + "type": "organizations", + "attributes": { + "email": "admin@example.com" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/hashicorp +``` + +### Sample Response + +**Note:** The `two-factor-conformant` and `assessments-enforced` properties are only returned from HCP Terraform organizations. + +```json +{ + "data": { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-Bzyc2JuegvVLAibn", + "created-at": "2021-08-30T18:09:57.561Z", + "email": "admin@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-public-modules": true, + "can-manage-public-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-provider": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + } +} +``` + +## Destroy an Organization + +`DELETE /organizations/:organization_name` + +| Parameter | Description | +| -------------------- | --------------------------------------- | +| `:organization_name` | The name of the organization to destroy | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | | The organization was successfully destroyed | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp +``` + +### Sample Response + +The response body will be empty if successful. + +## Show the Entitlement Set + +This endpoint shows the [entitlements](/terraform/enterprise/api-docs#feature-entitlements) for an organization. + +`GET /organizations/:organization_name/entitlement-set` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------ | +| `:organization_name` | The name of the organization's entitlement set to view | + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "entitlement-sets"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/entitlement-set +``` + +### Sample Response + +```json +{ + "data": { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets", + "attributes": { + "agents": false, + "audit-logging": false, + "configuration-designer": true, + "cost-estimation": false, + "global-run-tasks": false, + "module-tests-generation": false, + "operations": true, + "policy-enforcement": false, + "policy-limit": 5, + "policy-mandatory-enforcement-limit": null, + "policy-set-limit": 1, + "private-module-registry": true, + "private-policy-agents": false, + "private-vcs": false, + "run-task-limit": 1, + "run-task-mandatory-enforcement-limit": 1, + "run-task-workspace-limit": 10, + "run-tasks": false, + "self-serve-billing": true, + "sentinel": false, + "sso": false, + "state-storage": true, + "teams": false, + "usage-reporting": false, + "user-limit": 5, + "vcs-integrations": true, + "versioned-policy-set-limit": null + }, + "links": { + "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn" + } + } +} +``` + +## Show Module Producers + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. + + +This endpoint shows organizations that are configured to share modules with an organization through [Module Sharing](/terraform/enterprise/admin/application/module-sharing). + +`GET /organizations/:organization_name/relationships/module-producers` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------- | +| `:organization_name` | The name of the organization's module producers to view | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 module producers per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "hc-nomad", + "type": "organizations", + "attributes": { + "name": "hc-nomad", + "external-id": "org-ArQSQMAkFQsSUZjB" + }, + "links": { + "self": "/api/v2/organizations/hc-nomad" + } + } + ], + "links": { + "self": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`GET /organizations/:organization_name/relationships/data-retention-policy` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to show the data retention policy for. | + +This endpoint shows the data retention policy set explicitly on the organization. + +When no data retention policy is set for the organization, the endpoint returns the default policy configured for the Terraform Enterprise installation. Read more about [organization data retention policies](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies). + +For additional information, refer to [Data Retention Policy Types](/terraform/enterprise/api-docs/data-retention-policies#data-retention-policy-types) in the Terraform Enterprise documentation. + +## Create or update data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`POST /organizations/:organization_name/relationships/data-retention-policy` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to update the data retention policy for. | + +This endpoint creates a data retention policy for an organization or updates the existing policy. + +Read more about [organization data retention policies](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies). + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#create-or-update-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Remove data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`DELETE /organizations/:organization_name/relationships/data-retention-policy` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to remove the data retention policy for. | + +This endpoint removes the data retention policy explicitly set on an organization. +When the data retention policy is deleted, the organization inherits the default policy configured for the Terraform Enterprise installation. Refer to [Data Retention Policies](/terraform/enterprise/application-administration/general#data-retention-policies) for additional information. + +Refer to [Data Retention Policies](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies) for information about configuring data retention policies for an organization. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#remove-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ----------------- | ------------------------------------------------------------------------------------------ | +| `entitlement_set` | The entitlement set that determines which HCP Terraform features the organization can use. | + +## Relationships + +The following relationships may be present in various responses. + +| Resource Name | Description | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `module-producers` | Other organizations configured to share modules with the organization. | +| `oauth-tokens` | OAuth tokens associated with VCS configurations for the organization. | +| `authentication-token` | The API token for an organization. | +| `entitlement-set` | The entitlement set that determines which HCP Terraform features the organization can use. | +| `subscription` | The current subscription for an organization. | +| `default-agent-pool` | An organization's default agent pool. Set this value if your `default-execution-mode` is `agent`. | +| `data-retention-policy` | Specifies an organization's data retention policy. Refer to [Data Retention Policy APIs](/terraform/enterprise/api-docs/data-retention-policies) in the Terraform Enterprise documentation for more details. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/plan-exports.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/plan-exports.mdx new file mode 100644 index 0000000000..dabfc4fd47 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/plan-exports.mdx @@ -0,0 +1,226 @@ +--- +page_title: /plan-exports API reference for Terraform Enterprise +description: >- + Use the `/plan-exports` endpoint to manage plan exports for a Terraform run. + Create and show plan exports, or download and delete exported plan data. +source: terraform-docs-common +--- + +# Plan exports API reference + +Plan exports allow users to download data exported from the plan of a Run in a Terraform workspace. Currently, the only supported format for exporting plan data is to generate mock data for Sentinel. + +## Create a plan export + +`POST /plan-exports` + +This endpoint exports data from a plan in the specified format. The export process is asynchronous, and the resulting data becomes downloadable when its status is `"finished"`. The data is then available for one hour before expiring. After the hour is up, a new export can be created. + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "plan-exports"`) | Successfully created a plan export | +| [404][] | [JSON API error object][] | Plan not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.), or a plan export of the provided `data-type` is already pending or downloadable for this plan | + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------ | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"plan-exports"`. | +| `data.attributes.data-type` | string | | The format for the export. Currently, the only supported format is `"sentinel-mock-bundle-v0"`. | +| `data.relationships.plan.data` | object | | A JSON API relationship object that represents the plan being exported. This object must have a `type` of `plans`, and the `id` of a finished Terraform plan that does not already have a downloadable export of the specified `data-type` (e.g: `{"type": "plans", "id": "plan-8F5JFydVYAmtTjET"}`) | + +### Sample Payload + +```json +{ + "data": { + "type": "plan-exports", + "attributes": { + "data-type": "sentinel-mock-bundle-v0" + }, + "relationships": { + "plan": { + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/plan-exports +``` + +### Sample Response + +```json +{ + "data": { + "id": "pe-3yVQZvHzf5j3WRJ1", + "type": "plan-exports", + "attributes": { + "data-type": "sentinel-mock-bundle-v0", + "status": "queued", + "status-timestamps": { + "queued-at": "2019-03-04T22:29:53+00:00", + }, + }, + "relationships": { + "plan": { + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans" + } + } + }, + "links": { + "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1", + } + } +} +``` + +## Show a plan export + +`GET /plan-exports/:id` + +| Parameter | Description | +| --------- | ---------------------------------- | +| `id` | The ID of the plan export to show. | + +There is no endpoint to list plan exports. You can find IDs for plan exports in the +`relationships.exports` property of a plan object. + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "plan-exports"`) | The request was successful | +| [404][] | [JSON API error object][] | Plan export not found, or user unauthorized to perform action | + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1 +``` + +### Sample Response + +```json +{ + "data": { + "id": "pe-3yVQZvHzf5j3WRJ1", + "type": "plan-exports", + "attributes": { + "data-type": "sentinel-mock-bundle-v0", + "status": "finished", + "status-timestamps": { + "queued-at": "2019-03-04T22:29:53+00:00", + "finished-at": "2019-03-04T22:29:58+00:00", + "expired-at": "2019-03-04T23:29:58+00:00" + }, + }, + "relationships": { + "plan": { + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans" + } + } + }, + "links": { + "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1", + "download": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download" + } + } +} +``` + +## Download exported plan data + +`GET /plan-exports/:id/download` + +This endpoint generates a temporary URL to the location of the exported plan data in a `.tar.gz` archive, and then redirects to that link. If using a client that can follow redirects, you can use this endpoint to save the `.tar.gz` archive locally without needing to save the temporary URL. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [302][] | HTTP Redirect | Plan export found and temporary download URL generated | +| [404][] | [JSON API error object][] | Plan export not found, or user unauthorized to perform action | + +[302]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --location \ + https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download \ + > export.tar.gz +``` + +## Delete exported plan data + +`DELETE /plan-exports/:id` + +Plan exports expire after being available for one hour, but they can be deleted manually as well. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | No content | Plan export deleted successfully | +| [404][] | [JSON API error object][] | Plan export not found, or user unauthorized to perform action | + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + -X DELETE \ + https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1 +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/plans.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/plans.mdx new file mode 100644 index 0000000000..aee7e4eaef --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/plans.mdx @@ -0,0 +1,203 @@ +--- +page_title: /plans API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/plans` endpoint to read a Terraform run + plan or generate JSON-formatted execution plans. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[307]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Plans API reference + +A plan represents the execution plan of a Run in a Terraform workspace. + +## Attributes + +### Plan States + +The plan state is found in `data.attributes.status`, and you can reference the following list of possible states. + +| State | Description | +| ------------------------- | ----------------------------------------------------------------------------- | +| `pending` | The initial status of a plan once it has been created. | +| `managed_queued`/`queued` | The plan has been queued, awaiting backend service capacity to run terraform. | +| `running` | The plan is running. | +| `errored` | The plan has errored. This is a final state. | +| `canceled` | The plan has been canceled. This is a final state. | +| `finished` | The plan has completed successfully. This is a final state. | +| `unreachable` | The plan will not run. This is a final state. | + +## Show a plan + +`GET /plans/:id` + +| Parameter | Description | +| --------- | --------------------------- | +| `id` | The ID of the plan to show. | + +There is no endpoint to list plans. You can find the ID for a plan in the +`relationships.plan` property of a run object. + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "plans"`) | The request was successful | +| [404][] | [JSON API error object][] | Plan not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/plans/plan-8F5JFydVYAmtTjET +``` + +### Sample Response + +```json +{ + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans", + "attributes": { + "execution-details": { + "mode": "remote", + }, + "generated-configuration": false, + "has-changes": true, + "resource-additions": 0, + "resource-changes": 1, + "resource-destructions": 0, + "resource-imports": 0, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-07-02T22:29:53+00:00", + "pending-at": "2018-07-02T22:29:53+00:00", + "started-at": "2018-07-02T22:29:54+00:00", + "finished-at": "2018-07-02T22:29:58+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg" + }, + "relationships": { + "state-versions": { + "data": [] + } + }, + "links": { + "self": "/api/v2/plans/plan-8F5JFydVYAmtTjET", + "json-output": "/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output" + } + } +} +``` + +_Using HCP Terraform agents_ + +[HCP Terraform agents](/terraform/enterprise/api-docs/agents) allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. When a workspace is set to use the agent execution mode, the plan response will include additional details about the agent pool and agent used. + +```json +{ + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans", + "attributes": { + "execution-details": { + "agent-id": "agent-S1Y7tcKxXPJDQAvq", + "agent-name": "agent_01", + "agent-pool-id": "apool-Zigq2VGreKq7nwph", + "agent-pool-name": "first-pool", + "mode": "agent", + }, + "generated-configuration": false, + "has-changes": true, + "resource-additions": 0, + "resource-changes": 1, + "resource-destructions": 0, + "resource-imports": 0, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-07-02T22:29:53+00:00", + "pending-at": "2018-07-02T22:29:53+00:00", + "started-at": "2018-07-02T22:29:54+00:00", + "finished-at": "2018-07-02T22:29:58+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg" + }, + "relationships": { + "state-versions": { + "data": [] + } + }, + "links": { + "self": "/api/v2/plans/plan-8F5JFydVYAmtTjET", + "json-output": "/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output" + } + } +} +``` + +## Retrieve the JSON execution plan + +`GET /plans/:id/json-output` + +`GET /runs/:id/plan/json-output` + +These endpoints generate a temporary authenticated URL to the location of the [JSON formatted execution plan](/terraform/internals/json-format#format-summary). When successful, this endpoint responds with a temporary redirect that should be followed. If using a client that can follow redirects, you can use this endpoint to save the `.json` file locally without needing to save the temporary URL. + +This temporary URL provided by the redirect has a life of **1 minute**, and should not be relied upon beyond the initial request. If you need repeat access, you should use this endpoint to generate a new URL each time. + +-> **Note:** This endpoint is available for plans using Terraform 0.12 and later. For Terraform Enterprise, this endpoint is available from v202005-1, and its stability was improved in v202007-1. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) that has admin level access to the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------- | +| [204][] | No Content | Plan JSON supported, but plan has not yet completed. | +| [307][] | Temporary Redirect | Plan JSON found and temporary download URL generated | +| [422][] | [JSON API error object][] | Plan does not use a supported version of terraform (< 0.12.X) | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --location \ + https://app.terraform.io/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output | + > json-output.json +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policies.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policies.mdx new file mode 100644 index 0000000000..64118b2364 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policies.mdx @@ -0,0 +1,564 @@ +--- +page_title: /policies API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policies` endpoint to list, show, create, + upload, update, and delete Sentinel and OPA policies. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policies API reference + +Policies are rules that HCP Terraform enforces on Terraform runs. You can use policies to validate that the Terraform plan complies with security rules and best practices. HCP Terraform policy enforcement lets you use the policy-as-code frameworks Sentinel and Open Policy Agent (OPA) to apply policy checks to HCP Terraform workspaces. Refer to [Policy Enforcement](/terraform/enterprise/policy-enforcement) for more details. + +[Policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) are collections of policies that you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces, in your organization. For each run in the selected workspaces, HCP Terraform checks the Terraform plan against the policy set and displays the results in the UI. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +This page documents the API endpoints to create, read, update, and delete policies in an organization. To manage policy sets, use the [Policy Sets API](/terraform/enterprise/api-docs/policy-sets). To manage the policy results, use the [Runs API](/terraform/enterprise/api-docs/run). + +## Create a Policy + +`POST /organizations/:organization_name/policies` + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The organization to create the policy in. The organization must already exist in the system, and the token authenticating the API request must have permission to manage policies. (([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +\[permissions-citation]: #intentionally-unused---keep-for-maintainers) + +This creates a new policy object for the organization, but does not upload the actual policy code. After creation, you must use the [Upload a Policy endpoint (below)](#upload-a-policy) with the new policy's upload path. (This endpoint's response body includes the upload path in its `links.upload` property.) + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policies"`) | Successfully created a policy | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------- | -------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policies"`. | +| `data.attributes.name` | string | | The name of the policy, which can include letters, numbers, `-`, and `_`. You cannot modify this name after creation. | +| `data.attributes.description` | string | `null` | Text describing the policy's purpose. This field supports Markdown and appears in the HCP Terraform UI. | +| `data.attributes.kind` | string | `sentinel` | The policy-as-code framework for the policy. Valid values are `"sentinel"` and `"opa"`. | +| `data.attributes.query` | string | | The OPA query to run. Only valid for OPA policies. | +| `data.attributes.enforcement-level` | string | | The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | +| `data.attributes.enforce` | array\[object] | | **DEPRECATED** Use `enforcement-level` instead. An array of enforcement configurations that map policy file paths to their enforcement modes. Policies support a single file, so this array should consist of a single element. For Sentinel, if the path in the enforcement map does not match the Sentinel policy (`.sentinel`), then HCP Terraform uses the default `hard-mandatory` enforcement level. For OPA, the default enforcement level is `advisory`. | +| `data.attributes.enforce[].path` | string | | **DEPRECATED** For Sentinel, must be `.sentinel`, where `` has the same value as `data.attributes.name`. For OPA, must be `.rego`. | +| `data.attributes.enforce[].mode` | string | | **DEPRECATED** Use `enforcement-level` instead. The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | +| `data.relationships.policy-sets.data[]` | array\[object] | `[]` | A list of resource identifier objects to define which policy sets include the new policy. These objects must contain `id` and `type` properties, and the `type` property must be `policy-sets`. For example,`{ "id": "polset-3yVQZvHzf5j3WRJ1","type": "policy-sets" }`. | + +### Sample Payload (Sentinel) + +```json +{ + "data": { + "attributes": { + "enforcement-level": "hard-mandatory", + "name": "my-example-policy", + "description": "An example policy.", + "kind": "sentinel" + }, + "relationships": { + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "type": "policies" + } +} +``` + +### Sample Payload (OPA) + +-> **Note**: We have deprecated the `enforce` property in requests and responses but continue to provide it for backward compatibility. The below sample uses the deprecated `enforce` property. + +```json +{ + "data": { + "attributes": { + "enforce": [ + { + "path": "my-example-policy.rego", + "mode": "advisory" + } + ], + "name": "my-example-policy", + "description": "An example policy.", + "kind": "opa", + "query": "terraform.main" + }, + "relationships": { + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "type": "policies" + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/policies +``` + +### Sample Response (Sentinel) + +```json +{ + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policies", + "attributes": { + "name":"my-example-policy", + "description":"An example policy.", + "enforcement-level":"advisory", + "enforce": [ + { + "path":"my-example-policy.sentinel", + "mode":"advisory" + } + ], + "policy-set-count": 1, + "updated-at": null + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "links": { + "self":"/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload" + } + } +} +``` + +### Sample Response (OPA) + +```json +{ + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policies", + "attributes": { + "name":"my-example-policy", + "description":"An example policy.", + "kind": "opa", + "query": "terraform.main", + "enforcement-level": "advisory", + "enforce": [ + { + "path":"my-example-policy.rego", + "mode":"advisory" + } + ], + "policy-set-count": 1, + "updated-at": null + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "links": { + "self":"/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload" + } + } +} +``` + +## Show a Policy + +`GET /policies/:policy_id` + +| Parameter | Description | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:policy_id` | The ID of the policy to show. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policies"`) | The request was successful | +| [404][] | [JSON API error object][] | Policy not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/policies/pol-oXUppaX2ximkqp8w +``` + +### Sample Response + +```json +{ + "data": { + "id": "pol-oXUppaX2ximkqp8w", + "type": "policies", + "attributes": { + "name": "my-example-policy", + "description":"An example policy.", + "kind": "sentinel", + "enforcement-level": "soft-mandatory", + "enforce": [ + { + "path": "my-example-policy.sentinel", + "mode": "soft-mandatory" + } + ], + "policy-set-count": 1, + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "links": { + "self": "/api/v2/policies/pol-oXUppaX2ximkqp8w", + "upload": "/api/v2/policies/pol-oXUppaX2ximkqp8w/upload", + "download": "/api/v2/policies/pol-oXUppaX2ximkqp8w/download" + } + } +} +``` + +## Upload a Policy + +`PUT /policies/:policy_id/upload` + +| Parameter | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:policy_id` | The ID of the policy to upload code to. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding the policy ID. The ID also appears in the response when you create a policy. | + +This endpoint uploads code to an existing Sentinel or OPA policy. + +-> **Note**: This endpoint does not use JSON-API's conventions for HTTP headers and body serialization. + +-> **Note**: This endpoint limits the size of uploaded policies to 10MB. If a larger payload is uploaded, an HTTP 413 error will be returned, and the policy will not be saved. Consider refactoring policies into multiple smaller, more concise documents if you reach this limit. + +### Request Body + +This PUT endpoint requires the text of a valid Sentinel or OPA policy with a `Content-Type` of `application/octet-stream`. + +- Refer to [Defining Sentinel Policies](/terraform/enterprise/policy-enforcement/sentinel) for details about writing Sentinel code. +- Refer to [Defining OPA Policies](/terraform/enterprise/policy-enforcement/opa) for details about writing OPA code. + +### Sample Payload + +```plain +main = rule { true } +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @payload.file \ + https://app.terraform.io/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload +``` + +## Update a Policy + +`PATCH /policies/:policy_id` + +| Parameter | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:policy_id` | The ID of the policy to update. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding IDs. | + +This endpoint can update the enforcement mode of an existing policy. To update the policy code itself, use the upload endpoint. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policies"`) | Successfully updated the policy | +| [404][] | [JSON API error object][] | Policy not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policies"`. | +| `data.attributes.description` | string | `null` | Text describing the policy's purpose. This field supports Markdown and appears in the HCP Terraform UI. | +| `data.attributes.query` | string | | The OPA query to run. This is only valid for OPA policies. | +| `data.attributes.enforcement-level` | string | | The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | +| `data.attributes.enforce` | array\[object] | | **DEPRECATED** Use `enforcement-level` instead. An array of enforcement configurations that map policy file paths to their enforcement modes. Policies support a single file, so this array should consist of a single element. For Sentinel, if the path in the enforcement map does not match the Sentinel policy (`.sentinel`), then HCP Terraform uses the default `hard-mandatory` enforcement level. For OPA, the default enforcement level is `advisory`. | +| `data.attributes.enforce[].path` | string | | **DEPRECATED** For Sentinel, must be `.sentinel`, where `` has the same value as `data.attributes.name`. For OPA, must be `.rego`. | +| `data.attributes.enforce[].mode` | string | | **DEPRECATED** Use `enforcement-level` instead. The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "enforcement-level": "soft-mandatory" + }, + "type":"policies" + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/policies/pol-u3S5p2Uwk21keu1s +``` + +### Sample Response + +```json +{ + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policies", + "attributes": { + "name":"my-example-policy", + "description":"An example policy.", + "kind": "sentinel", + "enforcement-level": "soft-mandatory", + "enforce": [ + { + "path":"my-example-policy.sentinel", + "mode":"soft-mandatory" + } + ], + "policy-set-count": 0, + "updated-at":"2017-10-10T20:58:04.621Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + }, + "links": { + "self":"/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload", + "download":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/download" + } + } +} +``` + +## List Policies + +`GET /organizations/:organization_name/policies` + +| Parameter | Description | +| -------------------- | -------------------------------------- | +| `:organization_name` | The organization to list policies for. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | Array of [JSON API document][]s (`type: "policies"`) | Success | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------- | - | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 policies per page. | | +| `search[name]` | **Optional.** Allows searching the organization's policies by name. | | +| `filter[kind]` | **Optional.** If specified, restricts results to those with the matching policy kind value. Valid values are `sentinel` and `opa` | | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/policies +``` + +### Sample Response + +```json +{ + "data": [ + { + "attributes": { + "enforcement-level": "advisory", + "enforce": [ + { + "mode": "advisory", + "path": "my-example-policy.sentinel" + } + ], + "name": "my-example-policy", + "description": "An example policy.", + "policy-set-count": 0, + "updated-at": "2017-10-10T20:52:13.898Z", + "kind": "sentinel" + }, + "id": "pol-u3S5p2Uwk21keu1s", + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + }, + "links": { + "download": "/api/v2/policies/pol-u3S5p2Uwk21keu1s/download", + "self": "/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload": "/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload" + }, + "type": "policies" + }, + { + "id":"pol-vM2rBfj7V2Faq8By", + "type":"policies", + "attributes":{ + "name":"policy1", + "description":null, + "enforcement-level": "advisory", + "enforce":[ + { + "path":"policy1.rego", + "mode":"advisory" + } + ], + "policy-set-count":1, + "updated-at":"2022-09-13T04:57:43.516Z", + "kind":"opa", + "query":"data.terraform.rules.policy1.rule" + }, + "relationships":{ + "organization":{ + "data":{ + "id":"hashicorp", + "type":"organizations" + } + }, + "policy-sets":{ + "data":[ + { + "id":"polset-FYu3k5WY5eecwwdt", + "type":"policy-sets" + } + ] + } + }, + "links":{ + "self":"/api/v2/policies/pol-vM2rBfj7V2Faq8By", + "upload":"/api/v2/policies/pol-vM2rBfj7V2Faq8By/upload", + "download":"/api/v2/policies/pol-vM2rBfj7V2Faq8By/download" + } + } + ] +} +``` + +## Delete a Policy + +`DELETE /policies/:policy_id` + +| Parameter | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:policy_id` | The ID of the policy to delete. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the policy | +| [404][] | [JSON API error object][] | Policy not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/policies/pl-u3S5p2Uwk21keu1s +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | ------------------------------------------------------ | +| `policy_sets` | Policy sets that any returned policies are members of. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-checks.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-checks.mdx new file mode 100644 index 0000000000..621f40d368 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-checks.mdx @@ -0,0 +1,265 @@ +--- +page_title: /policy-checks API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policy-checks` endpoint to manage and + override the Sentinel policy checks that HCP Terraform performs during a run. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy checks API reference + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policy checks are the default workflow for Sentinel. Policy checks use the latest version of the Sentinel runtime and have access to cost estimation data. +This set of APIs provides endpoints to get, list, and override policy checks. + +~> **Warning:** Policy checks are deprecated and will be permanently removed in August 2025. We recommend that you start using policy evaluations to avoid disruptions. + +## List Policy Checks + +This endpoint lists the policy checks in a run. + +-> **Note**: The `sentinel` hash in the `result` attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk. + +`GET /runs/:run_id/policy-checks` + +| Parameter | Description | +| --------- | -------------------------------------------- | +| `run_id` | The ID of the run to list policy checks for. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 policy checks per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/runs/run-CZcmD7eagjhyXavN/policy-checks +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "polchk-9VYRc9bpfJEsnwum", + "type": "policy-checks", + "attributes": { + "result": { + "result": false, + "passed": 0, + "total-failed": 1, + "hard-failed": 0, + "soft-failed": 1, + "advisory-failed": 0, + "duration-ms": 0, + "sentinel": {...} + }, + "scope": "organization", + "status": "soft_failed", + "status-timestamps": { + "queued-at": "2017-11-29T20:02:17+00:00", + "soft-failed-at": "2017-11-29T20:02:20+00:00" + }, + "actions": { + "is-overridable": true + }, + "permissions": { + "can-override": false + } + }, + "relationships": { + "run": { + "data": { + "id": "run-veDoQbv6xh6TbnJD", + "type": "runs" + } + } + }, + "links": { + "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output" + } + } + ] +} +``` + +## Show Policy Check + +This endpoint gets information about a specific policy check ID. Policy check IDs can appear in audit logs. + +-> **Note**: The `sentinel` hash in the `result` attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk. + +`GET /policy-checks/:id` + +| Parameter | Description | +| --------- | ----------------------------------- | +| `id` | The ID of the policy check to show. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum +``` + +### Sample Response + +```json +{ + "data": { + "id": "polchk-9VYRc9bpfJEsnwum", + "type": "policy-checks", + "attributes": { + "result": { + "result": false, + "passed": 0, + "total-failed": 1, + "hard-failed": 0, + "soft-failed": 1, + "advisory-failed": 0, + "duration-ms": 0, + "sentinel": {...} + }, + "scope": "organization", + "status": "soft_failed", + "status-timestamps": { + "queued-at": "2017-11-29T20:02:17+00:00", + "soft-failed-at": "2017-11-29T20:02:20+00:00" + }, + "actions": { + "is-overridable": true + }, + "permissions": { + "can-override": false + } + }, + "relationships": { + "run": { + "data": { + "id": "run-veDoQbv6xh6TbnJD", + "type": "runs" + } + } + }, + "links": { + "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output" + } + } +} +``` + +## Override Policy + +This endpoint overrides a soft-mandatory or warning policy. + +-> **Note**: The `sentinel` hash in the `result` attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk. + +`POST /policy-checks/:id/actions/override` + +| Parameter | Description | +| --------- | --------------------------------------- | +| `id` | The ID of the policy check to override. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/actions/override +``` + +### Sample Response + +```json +{ + "data": { + "id": "polchk-EasPB4Srx5NAiWAU", + "type": "policy-checks", + "attributes": { + "result": { + "result": false, + "passed": 0, + "total-failed": 1, + "hard-failed": 0, + "soft-failed": 1, + "advisory-failed": 0, + "duration-ms": 0, + "sentinel": {...} + }, + "scope": "organization", + "status": "overridden", + "status-timestamps": { + "queued-at": "2017-11-29T20:13:37+00:00", + "soft-failed-at": "2017-11-29T20:13:40+00:00", + "overridden-at": "2017-11-29T20:14:11+00:00" + }, + "actions": { + "is-overridable": true + }, + "permissions": { + "can-override": false + } + }, + "links": { + "output": "/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/output" + } + } +} +``` + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| --------------- | ------------------------------------- | +| `run` | The run this policy check belongs to. | +| `run.workspace` | The associated workspace of the run. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-evaluations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-evaluations.mdx new file mode 100644 index 0000000000..9733bfbed1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-evaluations.mdx @@ -0,0 +1,288 @@ +--- +page_title: /policy-evaluations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policy-evaluations` endpoint to read + policy outcomes and evaluations from Sentinel and OPA policies that HCP + Terraform performs during a Terraform run. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy evaluations API reference + +Policy evaluations are run within the [HCP Terraform agents](/terraform/enterprise/api-docs/agents) in HCP Terraform's infrastructure. Policy evaluations do not have access to cost estimation data. +This set of APIs provides endpoints to list and get policy evaluations and policy outcomes. + +## List Policy Evaluations in the Task Stage + +Each run passes through several stages of action (pending, plan, policy check, apply, and completion), and shows the progress through those stages as [run states](/terraform/enterprise/run/states). +This endpoint allows you to list policy evaluations that are part of the task stage. + +`GET /task-stages/:task_stage_id/policy-evaluations` + +| Parameter | Description | +| ---------------- | ------------------------- | +| `:task_stage_id` | The task stage ID to get. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------- | +| [200][] | [JSON API document][] | Success | +| [404][] | [JSON API error object][] | Task stage not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not automatically encode URLs. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 agent pools per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi/policy-evaluations +``` + +### Sample Response + +```json +{ + "data":[ + { + "id":"poleval-8Jj9Hfoz892D9WMX", + "type":"policy-evaluations", + "attributes":{ + "status":"passed", + "policy-kind":"opa", + "policy-tool-version": "0.44.0", + "result-count": { + "advisory-failed":0, + "errored":0, + "mandatory-failed":0, + "passed":1 + } + "status-timestamps":{ + "passed-at":"2022-09-16T01:40:30+00:00", + "queued-at":"2022-09-16T01:40:04+00:00", + "running-at":"2022-09-16T01:40:08+00:00" + }, + "created-at":"2022-09-16T01:39:07.782Z", + "updated-at":"2022-09-16T01:40:30.010Z" + }, + "relationships":{ + "policy-attachable":{ + "data":{ + "id":"ts-yxskot8Gz5yHa38W", + "type":"task-stages" + } + }, + "policy-set-outcomes":{ + "links":{ + "related":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes" + } + } + }, + "links":{ + "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX" + } + } + ] +} +``` + +## List Policy Outcomes + +`GET /policy-evaluations/:policy_evaluation_id/policy-set-outcomes` + +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------- | +| `:policy_evaluation_id` | The ID of the policy evaluation the outcome belongs to get | + +This endpoint allows you to list policy set outcomes that are part of the policy evaluation. + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------- | +| [200][] | [JSON API document][] | Success | +| [404][] | [JSON API error object][] | Policy evaluation not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not automatically encode URLs. + +| Parameter | Description | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 policy sets per page. | +| `filter[n][status]` | **Optional.** If omitted, the endpoint returns all policies regardless of status. Must be either "passed", "failed", or "errored". | +| `filter[n][enforcementLevel]` | **Optional.** Only used if paired with a non-errored status filter. Must be either "advisory" or "mandatory." | + +-> **Note**: You can use `filter[n]` to combine combinations of statuses and enforcement levels. Policy outcomes with an errored status do not have an enforcement level. + +### Sample Request + +The following example requests demonstrate how to call the `policy-set-outcomes` endpoint using cuRL. + +#### All Policy Outcomes + +The following example call returns all policy set outcomes. + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes +``` + +#### Failed and Errored Policy Outcomes + +The following example call filters the response so that it only contains failed outcomes and errors. + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?filter[0][status]=errored&filter[1][status]=failed&filter[1][enforcementLevel]=mandatory +``` + +### Sample Response + +The following example response shows that the `policyVCS` policy failed. + +```json +{ + "data":[ + { + "id":"psout-cu8E9a97LBepZZXd", + "type":"policy-set-outcomes", + "attributes":{ + "outcomes":[ + { + "enforcement_level":"advisory", + "query":"data.terraform.main.main", + "status":"failed", + "policy_name":"policyVCS", + "description":"" + } + ], + "error":"", + "overridable":true, + "policy-set-name":"opa-policies-vcs", + "policy-set-description":null, + "result-count":{ + "advisory-failed":1, + "errored":0, + "mandatory-failed":0, + "passed":0 + }, + "policy-tool-version": "0.54.0" + }, + "relationships":{ + "policy-evaluation":{ + "data":{ + "id":"poleval-8Jj9Hfoz892D9WMX", + "type":"policy-evaluations" + } + } + } + } + ], + "links":{ + "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "first":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "prev":null, + "next":null, + "last":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20" + }, + "meta":{ + "pagination":{ + "current-page":1, + "page-size":20, + "prev-page":null, + "next-page":null, + "total-pages":1, + "total-count":1 + } + } +} +``` + +## Show a Policy Outcome + +`GET /policy-set-outcomes/:policy_set_outcome_id` + +| Parameter | Description | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `:policy_set_outcome_id` | The ID of the policy outcome to show. Refer to [List the Policy Outcomes](#list-policy-outcomes) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] | The request was successful | +| [404][] | [JSON API error object][] | Policy set outcome not found or user unauthorized to perform action | + +### Sample Request + +The following example request gets the outcomes for the `psout-cu8E9a97LBepZZXd` policy set. + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/policy-set-outcomes/psout-cu8E9a97LBepZZXd +``` + +### Sample Response + +The following example response shows that the `policyVCS` policy failed. + +```json +{ + "data":{ + "id":"psout-cu8E9a97LBepZZXd", + "type":"policy-set-outcomes", + "attributes":{ + "outcomes":[ + { + "enforcement_level":"advisory", + "query":"data.terraform.main.main", + "status":"failed", + "policy_name":"policyVCS", + "description":"" + } + ], + "error":"", + "overridable":true, + "policy-set-name":"opa-policies-vcs", + "policy-set-description":null, + "result-count":{ + "advisory-failed":1, + "errored":0, + "mandatory-failed":0, + "passed":0 + }, + "policy-tool-version": "0.54.0" + }, + "relationships":{ + "policy-evaluation":{ + "data":{ + "id":"poleval-8Jj9Hfoz892D9WMX", + "type":"policy-evaluations" + } + } + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-set-params.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-set-params.mdx new file mode 100644 index 0000000000..4065a72ca9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-set-params.mdx @@ -0,0 +1,290 @@ +--- +page_title: /parameters API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/parameters` endpoint to manage the + key/value pairs that Sentinel uses for policy checks. Read, create, update, + and delete parameters. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy set parameters API references + +[Sentinel parameters](/sentinel/docs/language/parameters) are a list of key/value pairs that HCP Terraform sends to the Sentinel runtime when performing policy checks on workspaces. They can help you avoid hardcoding sensitive parameters into a policy. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Parameters are only available for Sentinel policies. This set of APIs provides endpoints to create, update, list and delete parameters. + +## Create a Parameter + +`POST /policy-sets/:policy_set_id/parameters` + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:policy_set_id` | The ID of the policy set to create the parameter in. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the parameter. | +| `data.attributes.value` | string | `""` | The value of the parameter. | +| `data.attributes.category` | string | | The category of the parameters. Must be `"policy-set"`. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the parameter is written once and not visible thereafter. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "category":"policy-set", + "sensitive":false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "sensitive":false, + "category":"policy-set" + }, + "relationships": { + "configurable": { + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policy-sets" + }, + "links": { + "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s" + } + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-EavQ1LztoRTQHSNT" + } + } +} +``` + +## List Parameters + +`GET /policy-sets/:policy_set_id/parameters` + +| Parameter | Description | +| ---------------- | ------------------------------------------------ | +| `:policy_set_id` | The ID of the policy set to list parameters for. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 parameters per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ +"https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"var-AD4pibb9nxo1468E", + "type":"vars", + "attributes": { + "key":"name", + "value":"hello", + "sensitive":false, + "category":"policy-set", + }, + "relationships": { + "configurable": { + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policy-sets" + }, + "links": { + "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s" + } + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-AD4pibb9nxo1468E" + } + } + ] +} +``` + +## Update Parameters + +`PATCH /policy-sets/:policy_set_id/parameters/:parameter_id` + +| Parameter | Description | +| ---------------- | ------------------------------------------------- | +| `:policy_set_id` | The ID of the policy set that owns the parameter. | +| `:parameter_id` | The ID of the parameter to be updated. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.id` | string | | The ID of the parameter to update. | +| `data.attributes` | object | | New attributes for the parameter. This object can include `key`, `value`, `category` and `sensitive` properties, which are described above under [create a parameter](#create-a-parameter). All of these properties are optional; if omitted, a property will be left unchanged. | + +### Sample Payload + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "attributes": { + "key":"name", + "value":"mars", + "category":"policy-set", + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "sensitive":false, + "category":"policy-set", + }, + "relationships": { + "configurable": { + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policy-sets" + }, + "links": { + "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s" + } + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG" + } + } +} +``` + +## Delete Parameters + +`DELETE /policy-sets/:policy_set_id/parameters/:parameter_id` + +| Parameter | Description | +| ---------------- | ------------------------------------------------- | +| `:policy_set_id` | The ID of the policy set that owns the parameter. | +| `:parameter_id` | The ID of the parameter to be deleted. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-sets.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-sets.mdx new file mode 100644 index 0000000000..a0e73b0a9e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/policy-sets.mdx @@ -0,0 +1,1298 @@ +--- +page_title: /policy-sets API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policy-sets` endpoint to read, create, + delete, update and version Sentinel and OPA policy sets. Also, attach, + exclude, and detach policy sets to workspaces and projects. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy sets API reference + +[Policy Enforcement](/terraform/enterprise/policy-enforcement) lets you use the policy-as-code frameworks Sentinel and Open Policy Agent (OPA) to apply policy checks to HCP Terraform workspaces. + +[Policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) are collections of policies that you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. For each run in the selected workspaces, HCP Terraform checks the Terraform plan against the policy set. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +This API provides endpoints to create, read, update, and delete policy sets in an HCP Terraform organization. To view and manage individual policies, use the [Policies API](/terraform/enterprise/api-docs/policies). + +Many of these endpoints let you create policy sets from a designated repository in a Version Control System (VCS). For more information about how to configure a policy set VCS repository, refer to [Sentinel Policy Set VCS Repositories](/terraform/enterprise/policy-enforcement/sentinel/vcs) and [OPA Policy Set VCS Repositories](/terraform/enterprise/policy-enforcement/opa/vcs). + +Instead of connecting HCP Terraform to a VCS repository, you can use the the [Policy Set Versions endpoint](#create-a-policy-set-version) to create an entire policy set from a `tar.gz` file. + +Interacting with policy sets requires permission to manage policies. ([More about permissions](/terraform/enterprise/users-teams-organizations/permissions).) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a policy set + +`POST /organizations/:organization_name/policy-sets` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The organization to create the policy set in. The organization must already exist in the system, and the token authenticating the API request must have permission to manage policies. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "policy-sets"`) | Successfully created a policy set | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------------------------- | -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policy-sets"`. | +| `data.attributes.name` | string | | The name of the policy set. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.description` | string | `null` | Text describing the policy set's purpose. This field supports Markdown and appears in the HCP Terraform UI. | +| `data.attributes.global` | boolean | `false` | Whether HCP Terraform should automatically apply this policy set to all of an organization's workspaces. | +| `data.attributes.kind` | string | `sentinel` | The policy-as-code framework associated with the policy. Valid values are `sentinel` and `opa`. | +| `data.attributes.overridable` | boolean | `false` | Whether or not users can override this policy when it fails during a run. Valid for sentinel policies only if `agent-enabled` is set to `true`. | +| `data.attributes.vcs-repo` | object | `null` | VCS repository information. When present, HCP Terraform sources the policies and configuration from the specified VCS repository. This attribute and `policies` relationships are mutually exclusive, and you cannot use them simultaneously. | +| `data.attributes.vcs-repo.branch` | string | `null` | The branch of the VCS repository where HCP Terraform should retrieve the policy set. If empty, HCP Terraform uses the default branch. | +| `data.attributes.vcs-repo.identifier` | string | | The VCS repository identifier in the format `/`. For example, `hashicorp/my-policy-set`. The format for Azure DevOps is `//_git/`. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The OAuth Token ID HCP Terraform should use to connect to the VCS host. This value must not be specified if `github-app-installation-id` is specified. | +| `data.attributes.vcs-repo.github-app-installation-id` | string | | The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from **Account Settings** within HCP Terraform. You can not specify this value if `oauth-token-id` is specified. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | `false` | Whether HCP Terraform should instantiate repository submodules when retrieving the policy set. | +| `data.attributes.policies-path` | string | `null` | The VCS repository subdirectory that contains the policies for this policy set. HCP Terraform ignores files and directories outside of this sub-path and does not update the policy set when those files change. This attribute is only valid when you specify a VCS repository for the policy set. | +| `data.relationships.projects.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects are associated with the policy set. These objects must contain `id` and `type` properties, and the `type` property must be `projects`. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspaces.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which workspaces are associated with the policy set. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces`. For example, `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`. Obtain workspace IDs from the [workspace's settings page](/terraform/enterprise/workspaces/settings) or the [Show Workspace endpoint](/terraform/enterprise/api-docs/workspaces#show-workspace). You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspace-exclusions.data[]` | array\[object] | `[]` | A list of resource identifier objects specifying which workspaces HCP Terraform excludes from a policy set's enforcement. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces`. For example, `{ "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }`. | +| `data.relationships.policies.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which policies are members of the policy set. These objects must contain `id` and `type` properties, and the `type` property must be `policies`. For example, `{ "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }`. | +| `data.attributes.agent-enabled` | boolean | `false` | Only valid for `sentinel` policy sets. Whether this policy set should run as a policy evaluation in the HCP Terraform agent. | +| `data.attributes.policy-tool-version` | string | `latest` | The version of the tool that HCP Terraform uses to evaluate policies. You can only set a policy tool version for 'sentinel' policy sets if `agent-enabled` is `true`. | + +### Sample Payload + +```json +{ + "data": { + "type": "policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "global": false, + "kind": "sentinel", + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policies-path": "/policy-sets/foo", + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + } + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + } + } + } +} +``` + +### Sample payload with individual policy relationships + +```json +{ + "data": { + "type": "policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true + }, + "relationships": { + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/policy-sets +``` + +### Sample Response + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "workspace-count": 1, + "policies-path": "/policy-sets/foo", + "versioned": true, + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + }, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + }, + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +### Sample response with individual policy relationships + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## List policy sets + +`GET /organizations/:organization_name/policy-sets` + +| Parameter | Description | +| -------------------- | ----------------------------------------- | +| `:organization_name` | The organization to list policy sets for. | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-sets"`) | Request was successful | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `filter[versioned]` | **Optional.** Allows filtering policy sets based on whether they are versioned (VCS-managed or API-managed), or use individual policy relationships. Accepts a boolean true/false value. A `true` value returns versioned sets, and a `false` value returns sets with individual policy relationships. If omitted, all policy sets are returned. | +| `filter[kind]` | **Optional.** If specified, restricts results to those with the matching policy kind value. Valid values are `sentinel` and `opa`. | +| `include` | **Optional.** Enables you to include related resource data. Value must be a comma-separated list containing one or more of `projects`, `workspaces`, `workspace-exclusions`, `policies`, `newest_version`, or `current_version`. See the [relationships section](#relationships) for details. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 policy sets per page. | +| `search[name]` | **Optional.** Allows searching the organization's policy sets by name. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/policy-sets +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "workspace-count": 1, + "policies-path": "/policy-sets/foo", + "versioned": true, + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + }, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + }, + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } + ] +} +``` + +### Sample response with individual policy relationships + +```json +{ + "data": [ + { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + }, + ] +} +``` + +## Show a policy set + +`GET /policy-sets/:id` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to show. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-sets"`) | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `include` | **Optional.** Enables you to include related resource data. Value must be a comma-separated list containing one or more of `projects`, `workspaces`, `workspace-exclusions`, `policies`, `newest_version`, or `current_version`. See the [relationships section](#relationships) for details. | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1?include=current_version +``` + +### Sample Response + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 0, + "workspace-count": 1, + "policies-path": "/policy-sets/foo", + "versioned": true, + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + }, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "current-version": { + "data": { + "id": "polsetver-m4yhbUBCgyDVpDL4", + "type": "policy-set-versions" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + }, + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + }, + "included": [ + { + "id": "polsetver-m4yhbUBCgyDVpDL4", + "type": "policy-set-versions", + "attributes": { + "source": "github", + "status": "ready", + "status-timestamps": { + "ready-at": "2019-06-21T21:29:48+00:00", + "ingressing-at": "2019-06-21T21:29:47+00:00" + }, + "error": null, + "ingress-attributes": { + "commit-sha": "8766a423cb902887deb0f7da4d9beaed432984bb", + "commit-url": "https://github.com/hashicorp/my-policy-sets/commit/8766a423cb902887deb0f7da4d9beaed432984bb", + "identifier": "hashicorp/my-policy-sets" + }, + "created-at": "2019-06-21T21:29:47.792Z", + "updated-at": "2019-06-21T21:29:48.887Z" + }, + "relationships": { + "policy-set": { + "data": { + "id": "polset-a2mJwtmKygrA11dh", + "type": "policy-sets" + } + } + }, + "links": { + "self": "/api/v2/policy-set-versions/polsetver-E4S7jz8HMjBienLS" + } + } + ] +} +``` + +### Sample response with individual policy relationships + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z", + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +-> **Note:** The `data.relationships.projects` and `data.relationships.workspaces` refer to the projects and workspaces attached to the policy set. HCP Terraform omits these keys for policy sets marked as global, which are implicitly related to all of the organization's workspaces. + +## Update a policy set + +`PATCH /policy-sets/:id` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to update. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-sets"`) | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------- | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policy-sets"`. | +| `data.attributes.name` | string | (previous value) | The name of the policy set. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.description` | string | (previous value) | A description of the set's purpose. This field supports markdown and appears in the HCP Terraform UI. | +| `data.attributes.global` | boolean | (previous value) | Whether or not the policies in this set should be checked in all of the organization's workspaces or only in workspaces directly attached to the set. | +| `data.attributes.vcs-repo` | object | (previous value) | VCS repository information. When present, HCP Terraform sources the policies and configuration from the specified VCS repository instead of using definitions from HCP Terraform. Note that this option and `policies` relationships are mutually exclusive and may not be used simultaneously. | +| `data.attributes.vcs-repo.branch` | string | (previous value) | The branch of the VCS repo. When empty, HCP Terraform uses the VCS provider's default branch value. | +| `data.attributes.vcs-repo.identifier` | string | (previous value) | The VCS repository identifier in the the following format: `/`. An example identifier in GitHub is `hashicorp/my-policy-set`. The format for Azure DevOps is `//_git/`. | +| `data.attributes.vcs-repo.oauth-token-id` | string | (previous value) | The OAuth token ID to use to connect to the VCS host. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | (previous value) | Determines whether HCP Terraform instantiates repository submodules during the clone operation. | +| `data.attributes.policies-path` | boolean | (previous value) | The subdirectory of the attached VCS repository that contains the policies for this policy set. HCP Terraform ignores files and directories outside of the sub-path. Changes to the unrelated files do not update the policy set. You can only enable this option when a VCS repository is present. | +| `data.relationships.projects` | array\[object] | (previous value) | An array of references to projects that the policy set should be assigned to. Sending an empty array clears all project assignments. You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspaces` | array\[object] | (previous value) | An array of references to workspaces that the policy set should be assigned to. Sending an empty array clears all workspace assignments. You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspace-exclusions` | array\[object] | (previous value) | An array of references to excluded workspaces that HCP Terraform will not enforce this policy set upon. Sending an empty array clears all exclusions assignments. | +| `data.attributes.agent-enabled` | boolean | `false` | Only valid for `sentinel` policy sets. Whether this policy set should run as a policy evaluation in the HCP Terraform agent. | +| `data.attributes.policy-tool-version` | string | `latest` | The version of the tool that HCP Terraform uses to evaluate policies. You can only set a policy tool version for 'sentinel' policy sets if `agent-enabled` is `true`. | + +### Sample Payload + +```json +{ + "data": { + "type": "policy-sets", + "attributes": { + "name": "workspace-scoped-policy-set", + "description": "Policies added to this policy set will be enforced on specified workspaces", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0" + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1 +``` + +### Sample Response + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "workspace-scoped-policy-set", + "description": "Policies added to this policy set will be enforced on specified workspaces", + "global": false, + "kind": "sentinel", + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## Add policies to the policy set + +`POST /policy-sets/:id/relationships/policies` + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to add policies to. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more policies not found, wrong types, etc.) | + +~> **Note:** This endpoint may only be used when there is no VCS repository associated with the policy set. + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which policies will be added to the set. These objects must contain `id` and `type` properties, and the `type` property must be `policies` (e.g. `{ "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }, + { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies +``` + +## Attach a policy set to projects + +`POST /policy-sets/:id/relationships/projects` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to attach to projects. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** You can not attach global policy sets to individual projects. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which projects to attach the policy set to. These objects must contain `id` and `type` properties, and the `type` property must be `projects` (e.g. `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/projects +``` + +## Attach a policy set to workspaces + +`POST /policy-sets/:id/relationships/workspaces` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to attach to workspaces. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** Policy sets marked as global cannot be attached to individual workspaces. + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more workspaces not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines the workspaces the policy set will be attached to. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces +``` + +## Exclude a workspace from a policy set + +`POST /policy-sets/:id/relationships/workspace-exclusions` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:id` | The ID of a policy set that you want HCP Terraform to exclude from the workspaces you specify. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more excluded workspaces not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines the excluded workspaces the policy set will be attached to. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspace-exclusions +``` + +## Remove policies from the policy set + +`DELETE /policy-sets/:id/relationships/policies` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to remove policies from. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (wrong types, etc.) | + +~> **Note:** This endpoint may only be used when there is no VCS repository associated with the policy set. + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which policies will be removed from the set. These objects must contain `id` and `type` properties, and the `type` property must be `policies` (e.g. `{ "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }, + { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies +``` + +## Detach a policy set from projects + +`DELETE /policy-sets/:id/relationships/projects` + +| Parameter | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set you want to detach from the specified projects. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** You can not attach global policy sets to individual projects. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines the projects the policy set will be detached from. These objects must contain `id` and `type` properties, and the `type` property must be `projects`. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/projects +``` + +## Detach the policy set from workspaces + +`DELETE /policy-sets/:id/relationships/workspaces` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to detach from workspaces. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** Policy sets marked as global cannot be detached from individual workspaces. + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which workspaces the policy set will be detached from. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces +``` + +## Reinclude a workspace to a policy set + +`DELETE /policy-sets/:id/relationships/workspace-exclusions` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:id` | The ID of the policy set HCP Terraform should reinclude (enforce) on the specified workspaces. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which workspaces HCP Terraform should reinclude (enforce) this policy set on. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspace-exclusions +``` + +## Delete a policy set + +`DELETE /policy-sets/:id` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to delete. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | No Content | Successfully deleted the policy set | +| [404][] | [JSON API error object][] | Policy set not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1 +``` + +## Create a policy set version + +For versioned policy sets which have no VCS repository attached, versions of policy code may be uploaded directly to the API by creating a new policy set version and, in a subsequent request, uploading a tarball (tar.gz) of data to it. + +`POST /policy-sets/:id/versions` + +| Parameter | Description | +| --------- | ----------------------------------------------------- | +| `:id` | The ID of the policy set to create a new version for. | + +| Status | Response | Reason | +| ------- | ----------------------------------------------------- | ----------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "policy-set-versions"`) | The request was successful. | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | The policy set does not support uploading versions. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "polsetver-cXciu9nQwmk9Cfrn", + "type": "policy-set-versions", + "attributes": { + "source": "tfe-api", + "status": "pending", + "status-timestamps": {}, + "error": null, + "created-at": "2019-06-28T23:53:15.875Z", + "updated-at": "2019-06-28T23:53:15.875Z" + }, + "relationships": { + "policy-set": { + "data": { + "id": "polset-ws1CZBzm2h5K6ZT5", + "type": "policy-sets" + } + } + }, + "links": { + "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn", + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..." + } + } +} +``` + +The `upload` link URL in the above response is valid for one hour after creation. Make a `PUT` request to this URL directly, sending the policy set contents in `tar.gz` format as the request body. Once uploaded successfully, you can request the [Show Policy Set](#show-a-policy-set) endpoint again to verify that the status has changed from `pending` to `ready`. + +## Upload policy set versions + +`PUT https://archivist.terraform.io/v1/object/` + +The URL is provided in the `upload` attribute in the `policy-set-versions` resource. + +### Sample Request + +In the example below, `policy-set.tar.gz` is the local filename of the policy set version file to upload. + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @policy-set.tar.gz \ + https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox... +``` + +## Show a policy set version + +`GET /policy-set-versions/:id` + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the policy set version to show. | + +| Status | Response | Reason | +| ------- | ----------------------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-set-versions"`) | The request was successful. | +| [404][] | [JSON API error object][] | Policy set version not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --request GET \ + https://app.terraform.io/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn +``` + +### Sample Response + +```json +{ + "data": { + "id": "polsetver-cXciu9nQwmk9Cfrn", + "type": "policy-set-versions", + "attributes": { + "source": "tfe-api", + "status": "pending", + "status-timestamps": {}, + "error": null, + "created-at": "2019-06-28T23:53:15.875Z", + "updated-at": "2019-06-28T23:53:15.875Z" + }, + "relationships": { + "policy-set": { + "data": { + "id": "polset-ws1CZBzm2h5K6ZT5", + "type": "policy-sets" + } + } + }, + "links": { + "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn", + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..." + } + } +} +``` + +The `upload` link URL in the above response is valid for one hour after the `created_at` timestamp of the policy set version. Make a `PUT` request to this URL directly, sending the policy set contents in `tar.gz` format as the request body. Once uploaded successfully, you can request the [Show Policy Set Version](#show-a-policy-set-version) endpoint again to verify that the status has changed from `pending` to `ready`. + +## Available related resources + +The GET endpoints above can optionally return related resources for policy sets, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `current_version` | The most recent **successful** policy set version. | +| `newest_version` | The most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors. | +| `policies` | Individually managed policies which are associated with the policy set. | +| `projects` | The projects this policy set applies to. | +| `workspaces` | The workspaces this policy set applies to. | +| `workspace-exclusions` | The workspaces excluded from this policy set's enforcement. | + +The following resource types may be included for policy set versions: + +| Resource Name | Description | +| ------------- | ---------------------------------------------------------------- | +| `policy_set` | The policy set associated with the specified policy set version. | + +## Relationships + +The following relationships may be present in various responses for policy sets: + +| Resource Name | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `current-version` | The most recent **successful** policy set version. | +| `newest-version` | The most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors. | +| `organization` | The organization associated with the specified policy set. | +| `policies` | Individually managed policies which are associated with the policy set. | +| `projects` | The projects this policy set applies to. | +| `workspaces` | The workspaces this policy set applies to. | +| `workspace-exclusions` | The workspaces excluded from this policy set's enforcement. | + +The following relationships may be present in various responses for policy set versions: + +| Resource Name | Description | +| ------------- | ---------------------------------------------------------------- | +| `policy-set` | The policy set associated with the specified policy set version. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/gpg-keys.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/gpg-keys.mdx new file mode 100644 index 0000000000..3386ea42c3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/gpg-keys.mdx @@ -0,0 +1,388 @@ +--- +page_title: /gpg-keys API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/gpg-keys` endpoint to read, add, get, + update, and delete the GPG keys that HCP Terraform uses to sign private + providers. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# GPG keys API reference + +These endpoints are only relevant to private providers. When you [publish a private provider](/terraform/enterprise/registry/publish-providers) to the HCP Terraform private registry, you must upload the public key of the GPG key-pair that you used to sign the release. The HCP Terraform registry supports RSA or DSA formatted GPG keys. Refer to [Preparing and adding a signing key](/terraform/registry/providers/publishing#preparing-and-adding-a-signing-key) for more details. + +You need [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or [Manage Private Registry](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) permissions to add, update, or delete GPG keys in a private registry. + +## List GPG Keys + +`GET /api/registry/:registry_name/v2/gpg-keys` + +### Parameters + +| Parameter | Description | +| ---------------- | ------------------ | +| `:registry_name` | Must be `private`. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not automatically encode URLs. + +| Parameter | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[namespace]` | **Required.** A comma-separated list of one or more namespaces. The namespaces must be an authorized HCP Terraform or Terraform Enterprise organization name. | +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 GPG keys per page. | + +Gets a list of GPG keys belonging to the specified namespaces. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully fetched GPG keys | +| [400][] | [JSON API error object][] | Error - missing namespaces in request | +| [403][] | [JSON API error object][] | Forbidden - no authorized namespaces specified in request | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + "https://app.terraform.io/api/registry/private/v2/gpg-keys?filter%5Bnamespace%5D=my-organization,my-other-organization" +``` + +### Sample Response + +```json +{ + "data": [ + { + "type": "gpg-keys", + "id": "1", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----...", + "created-at": "2022-02-08T19:15:47Z", + "key-id": "C4E5E6C66C79C778", + "namespace": "my-other-organization", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-08T19:15:47Z" + }, + "links": { + "self": "/v2/gpg-keys/1" + } + }, + { + "type": "gpg-keys", + "id": "140", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----...", + "created-at": "2022-04-28T21:32:11Z", + "key-id": "C4E5E6C66C79C778", + "namespace": "my-organization", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-04-28T21:32:11Z" + }, + "links": { + "self": "/v2/gpg-keys/140" + } + } + ], + "links": { + "first": "/v2/gpg-keys?filter%5Bnamespace%5D=my-organization%2Cmy-other-organization&page%5Bnumber%5D=1&page%5Bsize%5D=15", + "last": "/v2/gpg-keys?filter%5Bnamespace%5D=my-organization%2Cmy-other-organization&page%5Bnumber%5D=1&page%5Bsize%5D=15", + "next": null, + "prev": null + }, + "meta": { + "pagination": { + "page-size": 15, + "current-page": 1, + "next-page": null, + "prev-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Add a GPG Key + +`POST /api/registry/:registry_name/v2/gpg-keys` + +### Parameters + +| Parameter | Description | +| ---------------- | ------------------ | +| `:registry_name` | Must be `private`. | + +Uploads a GPG Key to a private registry scoped with a namespace. The response will provide a "key-id", which is required to [Create a Provider Version](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-version). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully uploads a GPG key to a private provider | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"gpg-keys"`. | +| `data.attributes.namespace` | string | | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `data.attributes.ascii-armor` | string | | A valid gpg-key string. | + +### Sample Payload + +```json +{ + "data": { + "type": "gpg-keys", + "attributes": { + "namespace": "hashicorp", + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n" + } } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/registry/private/v2/gpg-keys +``` + +### Sample Response + +```json +{ + "data": { + "type": "gpg-keys", + "id": "23", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n", + "created-at": "2022-02-11T19:16:59Z", + "key-id": "32966F3FB5AC1129", + "namespace": "hashicorp", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-11T19:16:59Z" + }, + "links": { + "self": "/v2/gpg-keys/23" + } + } +} +``` + +## Get GPG Key + +`GET /api/registry/:registry_name/v2/gpg-keys/:namespace/:key_id` + +### Parameters + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider scoped to the GPG key. | +| `:key_id` | The id of the GPG key. | + +Gets the content of a GPG key. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ---------------------------------------------- | +| [200][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully fetched GPG key | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | GPG key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/registry/private/v2/gpg-keys/hashicorp/32966F3FB5AC1129 +``` + +### Sample Response + +```json +{ + "data": { + "type": "gpg-keys", + "id": "2", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n", + "created-at": "2022-02-24T17:07:25Z", + "key-id": "32966F3FB5AC1129", + "namespace": "hashicorp", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-24T17:07:25Z" + }, + "links": { + "self": "/v2/gpg-keys/2" + } + } +} +``` + +## Update a GPG Key + +`PATCH /api/registry/:registry_name/v2/gpg-keys/:namespace/:key_id` + +### Parameters + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider scoped to the GPG key. | +| `:key_id` | The id of the GPG key. | + +Updates the specified GPG key. Only the `namespace` attribute can be updated, and `namespace` has to match an `organization` the user has permission to access. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully updates a GPG key | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | GPG key not found or user not authorized | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"gpg-keys"`. | +| `data.attributes.namespace` | string | | The namespace of the provider. Must be the same as the `organization_name` for the provider. | + +### Sample Payload + +```json +{ + "data": { + "type": "gpg-keys", + "attributes": { + "namespace": "new-namespace", + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/registry/private/v2/gpg-keys/hashicorp/32966F3FB5AC1129 +``` + +### Sample Response + +```json +{ + "data": { + "type": "gpg-keys", + "id": "2", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n", + "created-at": "2022-02-24T17:07:25Z", + "key-id": "32966F3FB5AC1129", + "namespace": "new-name", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-24T17:12:10Z" + }, + "links": { + "self": "/v2/gpg-keys/2" + } + } +} +``` + +## Delete a GPG Key + +`DELETE /api/registry/:registry_name/v2/gpg-keys/:namespace/:key_id` + +### Parameters + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider scoped to the GPG key. | +| `:key_id` | The id of the GPG key. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully deletes a GPG key | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | GPG key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/registry/private/v2/gpg-keys/hashicorp/32966F3FB5AC1129 +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx new file mode 100644 index 0000000000..0b7f06da40 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx @@ -0,0 +1,272 @@ +--- +page_title: Manage module versions API reference for Terraform Enterprise +description: >- + Use the module management endpoints to deprecate and revert the deprecation of + module versions you published to an organization's private registry. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[503]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Manage module versions API reference + +This topic provides reference information about API endpoints that let your deprecate module versions in your organization’s private registry. + +## Introduction + +When you deprecate a module version, HCP Terraform adds warnings to the module's registry page and to run outputs when anyone uses the deprecated version. + + + +@include "tfc-package-callouts/manage-module-versions.mdx" + + + +After deprecating a module version, you can revert that deprecated status to remove the warnings from that version in the registry and outputs. For more details on module deprecation, refer to [Deprecate module versions](/terraform/enterprise/registry/manage-module-versions). + +## Deprecate a module version + +Use this endpoint to deprecate a module version. + +`PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version` + +| Parameter | Description | +| :------------------- | :------------------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | +| `:module_name` | The name of the module whose version you want to deprecate. | +| `:module_provider` | Specifies the Terraform provider that this module is used for. | +| `:module_version` | The module version you want to deprecate. | + +This endpoint allows you to deprecate a specific module version. Deprecating a module version adds warnings to the run output of any consumers using this module. + +| Status | Response | Reason | +| :----------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- | +| [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | [JSON API document](http://terraform/cloud-docs/api-docs#json-api-documents) | Successfully deprecated a module version. | +| [404](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | [JSON API error object](http://jsonapi.org/format/#error-objects) | This organization is not authorized to deprecate this module version, or the module version does not exist. | +| [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Malformed request body, for example the request is missing attributes or uses the wrong types. | +| [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) or [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Failure occurred while deprecating a module version. | + +### Sample payload + +```json +{ + "data": { + "type": "module-versions", + "attributes": { + "deprecation": { + "deprecated-status": "Deprecated", + "reason": "Deprecated due to a security vulnerability issue.", + "link": "https://www.hashicorp.com/" + } + } + } +} +``` + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ +https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0 +``` + +### Sample response + +```json +{ + "data": { + "type": "module-versions", + "id": "1", + "relationships": { + "deprecation": { + "data": { + "id": "2", + "type": "deprecations" + } + } + } + }, + "included": [ + { + "type": "deprecations", + "id": "2", + "attributes": { + "link": "https://www.hashicorp.com/", + "reason": "Deprecated due to a security vulnerability issue. Applies will be blocked in 15 days." + } + } + ] +} +``` + +## Revert the deprecation status for a module version + +Use this endpoint to revert the deprecation of a module version. + +`PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version` + +| Parameter | Description | +| :------------------- | :------------------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | +| `:module_name` | The name of the module you want to revert the deprecation of. | +| `:module_provider` | Specifies the Terraform provider that this module is used for. | +| `:module_version` | The module version you want to revert the deprecation of. | + +Deprecating a module version adds warnings to the run output of any consumers using this module. Reverting the deprecation status removes warnings from the output of consumers and fully reinstates the module version. + +| Status | Response | Reason | +| :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | +| [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | [JSON API document](http:///terraform/cloud-docs/api-docs#json-api-documents) | Successfully reverted a module version’s deprecation status and reinstated that version. | +| [404](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | [JSON API error object](http://jsonapi.org/format/#error-objects) | This organization is not authorized to revert the depreciation of this module version, or the module version does not exist. | +| [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Malformed request body, for example the request is missing attributes or uses the wrong types. | +| [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) or [503] | [JSON API error object](http://jsonapi.org/format/#error-objects) | Failure occurred while reverting the deprecation of a module version. | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ +https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0 +``` + +### Sample payload + +```json +{ + "data": { + "type": "module-versions", + "attributes": { + "deprecation": { + "deprecated-status": "Undeprecated" + } + } + } +} +``` + +### Sample response + +```json +{ + "data": { + "type": "module-versions", + "id": "1" + } +} +``` + +## Fetch a module version’s deprecation data + +Send a `GET` request to the `/modules/:GitHub-organization/:module/:provider/versions` endpoint to retrieve data about private registry modules, including the module's deprecation status. Refer to the [private registry module API example](/terraform/enterprise/api-docs/private-registry/modules#sample-registry-request-private-module) for additional information. + +For example, if you want to know the deprecation status of v0.0.1 of the `aws` provider’s `consul` module in your `my-cloud-org` organization, you could perform the following API call: + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/0.0.1 +``` + +If the module is deprecated, your response includes a `deprecation` key with the details of that module version’s deprecation. + +```json +{ + "id": "hashicorp/consul/aws/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "aws", + "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer" + // ... // + "deprecation": { + "reason": "This version was deprecated due to a vulnerability issue. Please upgrade to 0.0.2.", + "link": "https://hashicorp.com" + } +} +``` + +To check the deprecation status of all of the `consul` module’s versions, you could perform the following API call: + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/versions +``` + +The response includes multiple versions, and each version has a `deprecation` key listing the details of that module’s deprecation. If a module version has not been deprecated, the `deprecation` field returns `null`. + +```json +{ + "modules": [ + { + "source": "hashicorp/consul/aws", + "versions": [ + { + "version": "0.0.1", + // ... // + "deprecation": { + "reason": "security vulnerability", + "link": "www.hashicorp.com" + } + }, + { + "version": "0.0.2", + "submodules": [], + "root": { + "dependencies": [], + "providers": [ + { + "name": "template", + "version": "" + }, + { + "name": "aws", + "version": "" + } + ] + }, + "deprecation": null + } + ] + } + ] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/modules.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/modules.mdx new file mode 100644 index 0000000000..d5df734ece --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/modules.mdx @@ -0,0 +1,942 @@ +--- +page_title: /registry-modules API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/registry-modules` endpoint to read, + publish, update, delete, and add versions to modules in your organization's + private registry. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Registry modules API reference + +-> **Note:** Public Module Curation is only available in HCP Terraform. Where applicable, the `registry_name` parameter must be `private` for Terraform Enterprise. + +## HCP Terraform Registry Implementation + +The HCP Terraform Module Registry implements the [Registry standard API](/terraform/registry/api-docs) for consuming/exposing private modules. Refer to the [Module Registry HTTP API](/terraform/registry/api-docs) to perform the following: + +- Browse available modules +- Search modules by keyword +- List available versions for a specific module +- Download source code for a specific module version +- List latest version of a module for all providers +- Get the latest version for a specific module provider +- Get a specific module +- Download the latest version of a module + +For publicly curated modules, the HCP Terraform Module Registry acts as a proxy to the [Terraform Registry](https://registry.terraform.io) for the following: + +- List available versions for a specific module +- Get a specific module +- Get the latest version for a specific module provider + +The HCP Terraform Module Registry endpoints differs from the Module Registry endpoints in the following ways: + +- The `:namespace` parameter should be replaced with the organization name for private modules. +- The private module registry discovery endpoints have the path prefix provided in the [discovery document](/terraform/registry/api-docs#service-discovery) which is currently `/api/registry/v1`. +- The public module registry discovery endpoints have the path prefix provided in the [discovery document](/terraform/registry/api-docs#service-discovery) which is currently `/api/registry/public/v1`. +- [Authentication](/terraform/enterprise/api-docs#authentication) is handled the same as all other HCP Terraform endpoints. + +### Sample Registry Request (private module) + +List available versions for the `consul` module for the `aws` provider on the module registry published from the Github organization `my-gh-repo-org`: + +```shell +$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions +``` + +The same request for the same module and provider on the HCP Terraform module registry for the `my-cloud-org` organization: + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/versions +``` + +### Sample Proxy Request (public module) + +List available versions for the `consul` module for the `aws` provider on the module registry published from the Github organization `my-gh-repo-org`: + +```shell +$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions +``` + +The same request for the same module and provider on the HCP Terraform module registry: + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/public/v1/modules/my-gh-repo-org/consul/aws/versions +``` + +## List Registry Modules for an Organization + +`GET /organizations/:organization_name/registry-modules` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------ | +| `:organization_name` | The name of the organization to list available modules from. | + +Lists the modules that are available to a given organization. This includes the full list of publicly curated and private modules and is filterable. + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | -------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-modules"`) | The request was successful | +| [404][] | [JSON API error object][] | Modules not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `q` | **Optional.** A search query string. Modules are searchable by name, namespace, provider fields. | +| `filter[field name]` | **Optional.** If specified, restricts results to those with the matching field name value. Valid values are `registry_name`, `provider`, and `organization_name`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 registry modules per page. | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "mod-kwt1cBiX2SdDz38w", + "type": "registry-modules", + "attributes": { + "name": "api-gateway", + "namespace": "my-organization", + "provider": "alicloud", + "status": "setup_complete", + "version-statuses": [ + { + "version": "1.1.0", + "status": "ok" + } + ], + "created-at": "2021-04-07T19:01:18.528Z", + "updated-at": "2021-04-07T19:01:19.863Z", + "registry-name": "private", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/api-gateway/alicloud" + } + }, + { + "id": "mod-PopQnMtYDCcd3PRX", + "type": "registry-modules", + "attributes": { + "name": "aurora", + "namespace": "my-organization", + "provider": "aws", + "status": "setup_complete", + "version-statuses": [ + { + "version": "4.1.0", + "status": "ok" + } + ], + "created-at": "2021-04-07T19:04:41.375Z", + "updated-at": "2021-04-07T19:04:42.828Z", + "registry-name": "private", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/aurora/aws" + } + }, + ..., + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "prev": null, + "next": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=2&page%5Bsize%5D=6", + "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=29&page%5Bsize%5D=6" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 6, + "prev-page": null, + "next-page": 2, + "total-pages": 29, + "total-count": 169 + } + } +} +``` + +## Publish a Private Module from a VCS + +~> **Deprecation warning**: the following endpoint `POST /registry-modules` is replaced by the below endpoint and will be removed from future versions of the API! + +`POST /organizations/:organization_name/registry-modules/vcs` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to a team or team member with the **Manage modules** permission enabled. | + +Publishes a new registry private module from a VCS repository, with module versions managed automatically by the repository's tags. The publishing process will fetch all tags in the source repository that look like [SemVer](https://semver.org/) versions with optional 'v' prefix. For each version, the tag is cloned and the config parsed to populate module details (input and output variables, readme, submodules, etc.). The [Module Registry Requirements](/terraform/registry/modules/publish#requirements) define additional requirements on naming, standard module structure and tags for releases. + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-modules"`) | Successfully published module | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-modules"`. | +| `data.attributes.vcs-repo.identifier` | string | | The repository from which to ingress the configuration. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The VCS Connection (OAuth Connection + Token) to use as identified. Get this ID from the [oauth-tokens](/terraform/enterprise/api-docs/oauth-tokens) endpoint. You can not specify this value if `github-app-installation-id` is specified. | +| `data.attributes.vcs-repo.github-app-installation-id` | string | | The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from **Account Settings** within HCP Terraform. You can not specify this value if `oauth-token-id` is specified. | +| `data.attributes.vcs-repo.display_identifier` | string | | The display identifier for the repository. For most VCS providers outside of Bitbucket Cloud, this identifier matches the `data.attributes.vcs-repo.identifier` string. | +| `data.attributes.no-code` | boolean | | Allows you to enable or disable the no-code publishing workflow for a module. | +| `data.attributes.vcs-repo.branch` | string | | The repository branch to publish the module from if you are using the branch-based publishing workflow. If omitted, the module will be published using the tag-based publishing workflow. | + +A VCS repository identifier is a reference to a VCS repository in the format `:org/:repo`, where `:org` and `:repo` refer to the organization, or project key for Bitbucket Data Center, and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`. + +The OAuth Token ID identifies the VCS connection, and therefore the organization, that the module will be created in. + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "vcs-repo": { + "identifier":"lafentres/terraform-aws-my-module", + "oauth-token-id":"ot-hmAyP66qk2AMVdbJ", + "display_identifier":"lafentres/terraform-aws-my-module", + "branch": "main" + }, + "no-code": true + }, + "type":"registry-modules" + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/vcs +``` + +### Sample Response + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "namespace": "my-organization", + "registry-name": "private", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "vcs-repo": { + "branch": "", + "ingress-submodules": true, + "identifier": "lafentres/terraform-aws-my-module", + "display-identifier": "lafentres/terraform-aws-my-module", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..." + }, + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +## Create a Module (with no VCS connection) + +`POST /organizations/:organization_name/registry-modules` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to a team or team member with the **Manage modules** permission enabled. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Creates a new registry module without a backing VCS repository. + +#### Private modules + +After creating a module, a version must be created and uploaded in order to be usable. Modules created this way do not automatically update with new versions; instead, you must explicitly create and upload each new version with the [Create a Module Version](#create-a-module-version) endpoint. + +#### Public modules + +When created, the public module record will be available in the organization's registry module list. You cannot create versions for public modules as they are maintained in the public registry. + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-modules"`) | Successfully published module | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - public module curation disabled | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-modules"`. | +| `data.attributes.name` | string | | The name of this module. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters. | +| `data.attributes.provider` | string | | Specifies the Terraform provider that this module is used for. May contain lowercase alphanumeric characters. Maximum length is 64 characters. | +| `data.attributes.namespace` | string | | The namespace of this module. Cannot be set for private modules. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters. | +| `data.attributes.registry-name` | string | | Indicates whether this is a publicly maintained module or private. Must be either `public` or `private`. | +| `data.attributes.no-code` | boolean | | Allows you to enable or disable the no-code publishing workflow for a module. | + +### Sample Payload (private module) + +```json +{ + "data": { + "type": "registry-modules", + "attributes": { + "name": "my-module", + "provider": "aws", + "registry-name": "private", + "no-code": true + } + } +} +``` + +### Sample Payload (public module) + +```json +{ + "data": { + "type": "registry-modules", + "attributes": { + "name": "vpc", + "namespace": "terraform-aws-modules", + "provider": "aws", + "registry-name": "public", + "no-code": true + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules +``` + +### Sample Response (private module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "namespace": "my-organization", + "registry-name": "private", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +### Sample Response (public module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "vpc", + "namespace": "terraform-aws-modules", + "registry-name": "public", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws" + } + } +} +``` + +## Create a Module Version + +~> **Deprecation warning**: the following endpoint `POST /registry-modules/:organization_name/:name/:provider/versions` is replaced by the below endpoint and will be removed from future versions of the API! + +`POST /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/versions` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to a team or team member with the **Manage modules** permission enabled. | +| `:namespace` | The namespace of the module for which the version is being created. For private modules this is the same as the `:organization_name` parameter | +| `:name` | The name of the module for which the version is being created. | +| `:provider` | The name of the provider for which the version is being created. | +| `:registry-name` | Must be `private`. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Creates a new registry module version. This endpoint only applies to private modules without a VCS repository and VCS-linked branch based modules. VCS-linked tag-based modules automatically create new versions for new tags. After creating the version for a non-VCS backed module, you should upload the module to the link that HCP Terraform returns. + +| Status | Response | Reason | +| ------- | ---------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-module-versions"`) | Successfully published module version | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public modules | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------------- | ------ | ------- | --------------------------------------------------- | +| `data.type` | string | | Must be `"registry-module-versions"`. | +| `data.attributes.version` | string | | A valid semver version string. | +| `data.attributes.commit-sha` | string | | The commit SHA to use to create the module version. | + +### Sample Payload + +```json +{ + "data": { + "type": "registry-module-versions", + "attributes": { + "version": "1.2.3", + "commit-sha": "abcdef12345" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "modver-qjjF7ArLXJSWU3WU", + "type": "registry-module-versions", + "attributes": { + "source": "tfe-api", + "status": "pending", + "version": "1.2.3", + "created-at": "2018-09-24T20:47:20.931Z", + "updated-at": "2018-09-24T20:47:20.931Z" + }, + "relationships": { + "registry-module": { + "data": { + "id": "1881", + "type": "registry-modules" + } + } + }, + "links": { + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..." + } + } +} +``` + +## Add a Module Version (Private Module) + +`PUT https://archivist.terraform.io/v1/object/` + +**The URL is provided in the `upload` links attribute in the `registry-module-versions` resource.** + +### Expected Archive Format + +HCP Terraform expects the module version uploaded to be a gzip tarball with the module in the root (not in a subdirectory). + +Given the following folder structure: + + terraform-null-test + ├── README.md + ├── examples + │   └── default + │   ├── README.md + │   └── main.tf + └── main.tf + +Package the files in an archive format by running `tar zcvf module.tar.gz *` in the module's directory. + + ~$ cd terraform-null-test + terraform-null-test$ tar zcvf module.tar.gz * + a README.md + a examples + a examples/default + a examples/default/main.tf + a examples/default/README.md + a main.tf + +### Sample Request + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @module.tar.gz \ + https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox... +``` + +After the registry module version is successfully parsed, its status will become `"ok"`. + +## Get a Module + +~> **Deprecation warning**: the following endpoint `GET /registry-modules/show/:organization_name/:name/:provider` is replaced by the below endpoint and will be removed from future versions of the API! + +`GET /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider` + +### Parameters + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | +| `:namespace` | The namespace of the module. For private modules this is the name of the organization that owns the module. | +| `:name` | The module name. | +| `:provider` | The module provider. Must be lowercase alphanumeric. | +| `:registry-name` | Either `public` or `private`. | + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-modules"`) | The request was successful | +| [403][] | [JSON API error object][] | Forbidden - public module curation disabled | +| [404][] | [JSON API error object][] | Module not found or user unauthorized to perform action | + +### Sample Request (private module) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws +``` + +### Sample Request (public module) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws +``` + +### Sample Response (private module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "provider": "aws", + "namespace": "my-organization", + "registry-name": "private", + "status": "setup_complete", + "version-statuses": [ + { + "version": "1.0.0", + "status": "ok" + } + ], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T20:16:20.538Z", + "vcs-repo": { + "branch": "", + "ingress-submodules": true, + "identifier": "lafentres/terraform-aws-my-module", + "display-identifier": "lafentres/terraform-aws-my-module", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..." + }, + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +### Sample Response (public module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "vpc", + "provider": "aws", + "namespace": "terraform-aws-modules", + "registry-name": "public", + "status": "setup_complete", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T20:16:20.538Z", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws" + } + } +} +``` + +## Update a Private Registry Module + +`PATCH /organizations/:organization_name/registry-modules/private/:namespace/:name/:provider/` + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to update a module from. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The module namespace that the update affects. For private modules this is the name of the organization that owns the module. | +| `:name` | The module name that the update affects. | +| `:provider` | The name of the provider of the module that is being updated. | + +### Request Body + +These PATCH endpoints require a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"registry-modules"`. | +| `data.attributes.vcs-repo.branch` | string | (previous value) | The repository branch that Terraform executes tests and publishes new versions from. This cannot be used with the `data.attributes.vcs-repo.tags` key. | +| `data.attributes.vcs-repo.tags` | boolean | (previous value) | Whether the registry module should be tag-based. This cannot be used with the `data.attributes.vcs-repo.branch` key. | +| `data.attributes.test-config.tests-enabled` | boolean | (previous value) | Allows you to enable or disable tests for the module. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "vcs-repo": { + "branch": "main", + "tags": false + }, + "test-config": { + "tests-enabled": true + } + }, + "type": "registry-modules" + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/registry-name/registry-provider/ +``` + +### Sample Response + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "namespace": "my-organization", + "registry-name": "private", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "vcs-repo": { + "branch": "main", + "ingress-submodules": true, + "identifier": "lafentres/terraform-aws-my-module", + "display-identifier": "lafentres/terraform-aws-my-module", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..." + }, + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + }, + "test-config": { + "id": "tc-tcR6bxV5zE75Zb3B", + "tests-enabled": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +## Delete a Module + +
+ **Deprecation warning**: the following endpoints: + +- `POST /registry-modules/actions/delete/:organization_name/:name/:provider/:version` +- `POST /registry-modules/actions/delete/:organization_name/:name/:provider` +- `POST /registry-modules/actions/delete/:organization_name/:name` + +are replaced by the below endpoints and will be removed from future versions of the API! + +
+ +- `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/:version` +- `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider` +- `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name` + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to delete a module from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The module namespace that the deletion will affect. For private modules this is the name of the organization that owns the module. | +| `:name` | The module name that the deletion will affect. | +| `:provider` | If specified, the provider for the module that the deletion will affect. | +| `:version` | If specified, the version for the module and provider that will be deleted. | +| `:registry_name` | Either `public` or `private` | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +When removing modules, there are three versions of the endpoint, depending on how many parameters are specified. + +- If all parameters (module namespace, name, provider, and version) are specified, the specified version for the given provider of the module is deleted. +- If module namespace, name, and provider are specified, the specified provider for the given module is deleted along with all its versions. +- If only module namespace and name are specified, the entire module is deleted. + +For public modules, only the the endpoint specifying the module namespace and name is valid. The other DELETE endpoints will 404. +For public modules, this only removes the record from the organization's HCP Terraform Registry and does not remove the public module from registry.terraform.io. + +If a version deletion would leave a provider with no versions, the provider will be deleted. If a provider deletion would leave a module with no providers, the module will be deleted. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public module curation disabled | +| [404][] | [JSON API error object][] | Module, provider, or version not found or user not authorized | + +### Sample Request (private module) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/2.0.0 +``` + +### Sample Request (public module) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/provider-versions-platforms.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/provider-versions-platforms.mdx new file mode 100644 index 0000000000..029dda55df --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/provider-versions-platforms.mdx @@ -0,0 +1,707 @@ +--- +page_title: /registry-providers API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/registry-providers` endpoint to read, + create, and delete private providers versions and platforms in your private + registry. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Private provider versions and platforms API reference + +These endpoints are only relevant to private providers. When you [publish a private provider](/terraform/enterprise/registry/publish-providers) to the HCP Terraform private registry, you must also create at least one version and at least one platform for that version before consumers can use the provider in configurations. Unlike the public Terraform Registry, the private registry does not automatically upload new releases. You must manually add new provider versions and the associated release files. + +All members of an organization can view and use both public and private providers, but you need [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or [Manage Private Registry](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) permissions to add, update, or delete provider versions and platforms in private registry. + +## Create a Provider Version + +`POST /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions` + +The private registry does not automatically update private providers when you release new versions. You must use this endpoint to add each new version. Consumers cannot use new versions until you upload all [required release files](/terraform/enterprise/registry/publish-providers#release-files) and [Create a Provider Platform](#create-a-provider-platform). + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a provider in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the version is being created. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the version is being created. | + +Creates a new registry provider version. This endpoint only applies to private providers. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-provider-versions"`) | Success | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-provider-versions"`. | +| `data.attributes.version` | string | | A valid semver version string. | +| `data.attributes.key-id` | string | | A valid gpg-key string. | +| `data.attributes.protocols` | array | | An array of Terraform provider API versions that this version supports. Must be one or all of the following values `["4.0","5.0","6.0"]`. | + +-> **Note:** Only Terraform 0.13 and later support third-party provider registries, and that Terraform version requires provider API version 5.0 or later. So you do not need to list major versions 4.0 or earlier in the `protocols` attribute. + +### Sample Payload + +```json +{ + "data": { + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"] + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "created-at": "2022-02-11T19:16:59.876Z", + "updated-at": "2022-02-11T19:16:59.876Z", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"], + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "shasums-uploaded": false, + "shasums-sig-uploaded": false + }, + "relationships": { + "registry-provider": { + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers" + } + }, + "platforms": { + "data": [], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms" + } + } + }, + "links": { + "shasums-upload": "https://archivist.terraform.io/v1/object/dmF1b...", + "shasums-sig-upload": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} + +``` + +## Get All Versions for a Single Provider + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "created-at": "2022-02-11T19:16:59.876Z", + "updated-at": "2022-02-11T19:16:59.876Z", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"], + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "shasums-uploaded": true, + "shasums-sig-uploaded": true + }, + "relationships": { + "registry-provider": { + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers" + } + }, + "platforms": { + "data": [ + { + "id": "provpltfrm-GSHhNzptr9s3WoLD", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-A1PHitiM2KkKpVoM", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-qQYosUguetYtXGzJ", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-pjDHFN46y193bS7t", + "type": "registry-provider-platforms" + } + ], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms" + } + } + }, + "links": { + "shasums-download": "https://archivist.terraform.io/v1/object/dmF1b...", + "shasums-sig-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +**Note:** The `shasums-uploaded` and `shasums-sig-uploaded` properties will be false if those files have not been uploaded to Archivist. In this case, instead of including links to `shasums-download` and `shasums-sig-download`, the response will include upload links (`shasums-upload` and `shasums-sig-upload`). + +## Get a Version + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | +| `:version` | The version of the provider being created to which different platforms can be added. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1 +``` + +### Sample Response + +```json +{ + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "created-at": "2022-02-11T19:16:59.876Z", + "updated-at": "2022-02-11T19:16:59.876Z", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"], + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "shasums-uploaded": true, + "shasums-sig-uploaded": true + }, + "relationships": { + "registry-provider": { + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers" + } + }, + "platforms": { + "data": [ + { + "id": "provpltfrm-GSHhNzptr9s3WoLD", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-A1PHitiM2KkKpVoM", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-qQYosUguetYtXGzJ", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-pjDHFN46y193bS7t", + "type": "registry-provider-platforms" + } + ], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms" + } + } + }, + "links": { + "shasums-download": "https://archivist.terraform.io/v1/object/dmF1b...", + "shasums-sig-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} +``` + +**Note:** `shasums-uploaded` and `shasums-sig-uploaded` will be false if those files haven't been uploaded to Archivist yet. In this case, instead of including links to `shasums-download` and `shasums-sig-download`, the response will include upload links (`shasums-upload` and `shasums-sig-upload`). + +## Delete a Version + +`DELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:provider_version` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to delete a provider version from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the version is being deleted. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the version is being deleted. | +| `:version` | The version for the provider that will be deleted along with its corresponding platforms. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user not authorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/public/hashicorp/aws/versions/3.1.1 +``` + +## Create a Provider Platform + +`POST /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms` + +Platforms are binaries that allow the provider to run on a particular operating system and architecture combination (e.g., Linux and AMD64). GoReleaser creates binaries automatically when you [create a release on GitHub](/terraform/registry/providers/publishing#creating-a-github-release) or [create a release locally](/terraform/registry/providers/publishing#using-goreleaser-locally). + +You must upload one or more platforms for each version of a private provider. After you create a platform, you must upload the platform binary file to the `provider-binary-upload` URL. + +### Parameters + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a provider platform in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the platform is being created. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the platform is being created. | +| `:version` | The provider version of the provider for which the platform is being created. | + +Creates a new registry provider platform. This endpoint only applies to private providers. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-provider-platforms"`) | Success | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | ---------------------------------------- | +| `data.type` | string | | Must be `"registry-provider-platforms"`. | +| `data.attributes.os` | string | | A valid operating system string. | +| `data.attributes.arch` | string | | A valid architecture string. | +| `data.attributes.shasum` | string | | A valid shasum string. | +| `data.attributes.filename` | string | | A valid filename string. | + +### Sample Payload + +```json +{ + "data": { + "type": "registry-provider-version-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "shasum": "8f69533bc8afc227b40d15116358f91505bb638ce5919712fbb38a2dec1bba38", + "filename": "terraform-provider-aws_3.1.1_linux_amd64.zip" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms +``` + +### Sample Response + +```json +{ + "data": { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "filename": "terraform-provider-aws_3.1.1_linux_amd64.zip", + "shasum": "8f69533bc8afc227b40d15116358f91505bb638ce5919712fbb38a2dec1bba38", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": false + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-upload": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} + +``` + +## Get All Platforms for a Single Version + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | +| `:version` | The version of the provider. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "provpltfrm-GSHhNzptr9s3WoLD", + "type": "registry-provider-platforms", + "attributes": { + "os": "darwin", + "arch": "amd64", + "filename": "terraform-provider-aws_3.1.1_darwin_amd64.zip", + "shasum": "fd580e71bd76d76913e1925f2641be9330c536464af9a08a5b8994da65a26cbc", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": true + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + }, + { + "id": "provpltfrm-A1PHitiM2KkKpVoM", + "type": "registry-provider-platforms", + "attributes": { + "os": "darwin", + "arch": "arm64", + "filename": "terraform-provider-aws_3.1.1_darwin_arm64.zip", + "shasum": "de3c351d7f35a3c8c583c0da5c1c4d558b8cea3731a49b15f63de5bbbafc0165", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": true + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +**Note:** The `provider-binary-uploaded` property will be `false` if that file has not been uploaded to Archivist. In this case, instead of including a link to `provider-binary-download`, the response will include an upload link `provider-binary-upload`. + +## Get a Platform + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms/:os/:arch` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | +| `:version` | The version of the provider. | +| `:os` | The operating system of the provider platform. | +| `:arch` | The architecture of the provider platform. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms/linux/amd64 +``` + +### Sample Response + +```json +{ + "data": { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "filename": "terraform-provider-aws_3.1.1_linux_amd64.zip", + "shasum": "8f69533bc8afc227b40d15116358f91505bb638ce5919712fbb38a2dec1bba38", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": true + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} +``` + +**Note:** The `provider-binary-uploaded` property will be `false` if that file has not been uploaded to Archivist. In this case, instead of including a link to `provider-binary-download`, the response will include an upload link `provider-binary-upload`. + +## Delete a Platform + +`DELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms/:os/:arch` + +### Parameters + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to delete a provider platform from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the platform is being deleted. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the platform is being deleted. | +| `:version` | The version for which the platform is being deleted. | +| `:os` | The operating system of the provider platform that is being deleted. | +| `:arch` | The architecture of the provider platform that is being deleted. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user not authorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms/linux/amd64 +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/providers.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/providers.mdx new file mode 100644 index 0000000000..44719c2f16 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/providers.mdx @@ -0,0 +1,471 @@ +--- +page_title: /registry-providers API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's organization `/registry-providers` endpoint + to list, create, get, and delete providers in your private registry. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Registry providers API reference + +You can add publicly curated providers from the [Terraform Registry](https://registry.terraform.io/) and custom, private providers to your HCP Terraform private registry. The private registry stores a pointer to public providers so that you can view their data from within HCP Terraform. This lets you clearly designate all of the providers that are recommended for the organization and makes them centrally accessible. + +All members of an organization can view and use both public and private providers, but you need [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or [Manage Private Registry](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) permissions to add, update, or delete them them in private registry. + +## HCP Terraform Registry Implementation + +For publicly curated providers, the HCP Terraform Registry acts as a proxy to the [Terraform Registry](https://registry.terraform.io) for the following: + +- The public registry discovery endpoints have the path prefix provided in the [discovery document](/terraform/registry/api-docs#service-discovery) which is currently `/api/registry/public/v1`. +- [Authentication](/terraform/enterprise/api-docs#authentication) is handled the same as all other HCP Terraform endpoints. + +## List Terraform Registry Providers for an Organization + +`GET /organizations/:organization_name/registry-providers` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------- | +| `:organization_name` | The name of the organization to list available providers from. | + +Lists the providers included in the private registry for the specified organization. + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | ---------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [404][] | [JSON API error object][] | Providers not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Providers are searchable by both their name and their namespace fields. | +| `filter[field name]` | **Optional.** If specified, restricts results to those with the matching field name value. Valid values are `registry_name`, and `organization_name`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 registry providers per page. | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-providers +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "prov-kwt1cBiX2SdDz38w", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "my-organization", + "created-at": "2021-04-07T19:01:18.528Z", + "updated-at": "2021-04-07T19:01:19.863Z", + "registry-name": "public", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aws" + } + }, + { + "id": "prov-PopQnMtYDCcd3PRX", + "type": "registry-providers", + "attributes": { + "name": "aurora", + "namespace": "my-organization", + "created-at": "2021-04-07T19:04:41.375Z", + "updated-at": "2021-04-07T19:04:42.828Z", + "registry-name": "public", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aurora" + } + }, + ..., + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "prev": null, + "next": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=2&page%5Bsize%5D=6", + "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=29&page%5Bsize%5D=6" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 6, + "prev-page": null, + "next-page": 2, + "total-pages": 29, + "total-count": 169 + } + } +} +``` + +## Create a Provider + +`POST /organizations/:organization_name/registry-providers` + +Use this endpoint to create both public and private providers: + +- **Public providers:** The public provider record will be available in the organization's registry provider list immediately after creation. You cannot create versions for public providers; you must use the versions available on the Terraform Registry. +- **Private providers:** The private provider record will be available in the organization's registry provider list immediately after creation, but you must [create a version and upload release assets](/terraform/enterprise/registry/publish-providers#publishing-a-provider-and-creating-a-version) before consumers can use it. The private registry does not automatically update private providers when you release new versions. You must add each new version with the [Create a Provider Version](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-version) endpoint. + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a provider in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-providers"`) | Successfully published provider | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +~> **Important:** For private providers, you must also create a version, a platform, and upload release assets before consumers can use the provider. Refer to [Publishing a Private Provider](/terraform/enterprise/registry/publish-providers) for more details. + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"registry-providers"`. | +| `data.attributes.name` | string | | The name of the provider. | +| `data.attributes.namespace` | string | | The namespace of the provider. For private providers this is the same as the `:organization_name` parameter. | +| `data.attributes.registry-name` | string | | Whether this is a publicly maintained provider or private. Must be either `public` or `private`. | + +### Sample Payload (Private Provider) + +```json +{ + "data": { + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "private" + } + } +} +``` + +### Sample Payload (Public Provider) + +```json +{ + "data": { + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "public" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-providers +``` + +### Sample Response (Private Provider) + +```json +{ + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "private", + "created-at": "2022-02-11T19:16:59.533Z", + "updated-at": "2022-02-11T19:16:59.533Z", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "versions": { + "data": [], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } +} +``` + +### Sample Response (Public Provider) + +```json +{ + "data": { + "id": "prov-fZn7uHu99ZCpAKZJ", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "public", + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws" + } + } +} +``` + +## Get a Provider + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name` + +### Parameters + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Whether this is a publicly maintained provider or private. Must be either `public` or `private`. | +| `:namespace` | The namespace of the provider. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The provider name. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request (Private Provider) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws +``` + +### Sample Request (Public Provider) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws +``` + +### Sample Response (Private Provider) + +```json +{ + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "created-at": "2022-02-11T19:16:59.533Z", + "updated-at": "2022-02-11T19:16:59.533Z", + "registry-name": "private", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "versions": { + "data": [ + { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + ], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } +} +``` + +### Sample Response (Public Provider) + +```json +{ + "data": { + "id": "prov-fZn7uHu99ZCpAKZJ", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "public", + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T20:16:20.538Z", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws" + } + } +} +``` + +## Delete a Provider + +`DELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name` + +### Parameters + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to delete a provider from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Whether this is a publicly maintained provider or private. Must be either `public` or `private`. | +| `:namespace` | The namespace of the provider that will be deleted. | +| `:name` | The name of the provider that will be deleted. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user not authorized to perform action | + +### Sample Request (Private Provider) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws +``` + +### Sample Request (Public Provider) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/tests.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/tests.mdx new file mode 100644 index 0000000000..ea1b7f4b60 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/private-registry/tests.mdx @@ -0,0 +1,755 @@ +--- +page_title: /tests API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/tests` endpoint to list, get, create, and + cancel Terraform test runs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Tests API reference + +Tests are terraform operations(runs) and are referred to as Test Runs within the HCP Terraform API. + +Performing a test on a new configuration is a multi-step process. + +1. [Create a configuration version on the registry module](#create-a-configuration-version-for-a-test). +2. [Upload configuration files to the configuration version](#upload-configuration-files-for-a-test). +3. [Create a test on the module](#create-a-test-run); HCP Terraform completes this step automatically when you upload a configuration file. + +Alternatively, you can create a test with a pre-existing configuration version, even one from another module. This is useful for promoting known good code from one module to another. + +## Attributes + +The `tests` API endpoint has the following attributes. + +### Test Run States + +The state of the test operation is found in `data.attributes.status`, and you can reference the following list of possible states. + +| State | Description | +| ---------- | ----------------------------------------------------- | +| `pending` | The initial status of a run after creation. | +| `queued` | HCP Terraform has queued the test operation to start. | +| `running` | HCP Terraform is executing the test. | +| `errored` | The test has errored. This is a final state. | +| `canceled` | The test has been canceled. This is a final state. | +| `finished` | The test has completed. This is a final state. | + +### Test run status + +The final test status is found in `data.attributes.test-status`, and you can reference the following list of possible states. + +| Status | Description | +| ------ | ---------------------------- | +| `pass` | The given tests have passed. | +| `fail` | The given tests have failed. | + +### Detailed test status + +The test results can be found via the following attributes + +| Status | Description | | +| ------------------------------- | ------------------------------------------- | - | +| `data.attributes.tests-passed` | The number of tests that have passed. | | +| `data.attributes.tests-failed` | The number of tests that have failed. | | +| `data.attributes.tests-errored` | The number of tests that have errored out. | | +| `data.attributes.tests-skipped` | The number of tests that have been skipped. | | + +### Test Sources + +List tests for a module. You can use the following sources as [tests list](/terraform/enterprise/api-docs/private-registry/tests#list-tests-for-a-module) query parameters. + +| Source | Description | +| --------------------------- | ---------------------------------------------------------------------------------------- | +| `terraform` | Indicates a test was queued from HCP Terraform CLI. | +| `tfe-api` | Indicates a test was queued from HCP Terraform API. | +| `tfe-configuration-version` | Indicates a test was queued from a Configuration Version, triggered from a VCS provider. | + +## Create a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the test is being created. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test is being created. | +| `:provider` | The name of the provider for which the test is being created. | + +A test run executes tests against a registry module, using a configuration version and the modules’s current environment variables. + +Creating a test run requires permission to access the specified module. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for more information. + +When creating a test run, you may optionally provide a list of variable objects containing key and value attributes. These values apply to that test run specifically and take precedence over variables with the same key that are created within the module. All values must be expressed as an HCL literal in the same syntax you would use when writing Terraform code. + +**Sample Test Variables:** + +```json +"attributes": { + "variables": [ + { "key": "replicas", "value": "2" }, + { "key": "access_key", "value": "\"ABCDE12345\"" } + ] +} +``` + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------------------------------------- | -------------------- | ------------- | -------------------------------------------------------------------------------------------------- | +| `data.attributes.verbose` | bool | `false` | Specifies whether Terraform should print the plan or state for each test run block as it executes. | +| `data.attributes.test-directory` | string | `"tests"` | Sets the directory where HCP Terraform executes the tests. | +| `data.attributes.filters` | array\[string] | (empty array) | When specified, HCP Terraform only executes the test files contained within this array. | +| `data.attributes.variables` | array\[{key, value}] | (empty array) | Specifies an optional list of test-specific environment variable values. | +| `data.relationships.configuration-version.data.id` | string | none | Specifies the configuration version that HCP Terraform executes the test against. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "verbose": true, + "filters": ["tests/test.tftest.hcl"], + "test-directory": "tests", + "variables": [ + { "key" : "number", "value": 4} + ] + }, + "type":"test-runs" + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/private/registry-provider/test-runs +``` + +### Sample Response + +```json +{ + "data": { + "id": "trun-KFg8DSiRz4E37mdJ", + "type": "test-runs", + "attributes": { + "status": "queued", + "status-timestamps": { + "queued-at": "2023-10-03T18:27:39+00:00" + }, + "created-at": "2023-10-03T18:27:39.239Z", + "updated-at": "2023-10-03T18:27:39.264Z", + "test-configurable-type": "RegistryModule", + "test-configurable-id": "mod-9rjVHLCUE9QD3k6L", + "variables": [ + { + "key": "number", + "value": "4" + } + ], + "filters": [ + "tests/test.tftest.hcl" + ], + "test-directory": "tests", + "verbose": true, + "test-status": null, + "tests-passed": null, + "tests-failed": null, + "tests-errored": null, + "tests-skipped": null, + "source": "tfe-api", + "message": "Queued manually via the Terraform Enterprise API" + }, + "relationships": { + "configuration-version": { + "data": { + "id": "cv-d3zBGFf5DfWY4GY9", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9" + } + }, + "created-by": { + "data": { + "id": "user-zsRFs3AGaAHzbEfs", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs" + } + } + } + } +} +``` + +## Create a Configuration Version for a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/configuration-versions` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the configuration version is being created. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the configuration version is being created. | +| `:provider` | The name of the provider for which the configuration version is being created. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/configuration-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "cv-aaady7niJMY1wAvx", + "type": "configuration-versions", + "attributes": { + "auto-queue-runs": true, + "error": null, + "error-message": null, + "source": "tfe-api", + "speculative": false, + "status": "pending", + "status-timestamps": {}, + "changed-files": [], + "provisional": false, + "upload-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv" + }, + "relationships": { + "ingress-attributes": { + "data": null, + "links": { + "related": "/api/v2/configuration-versions/cv-aaady7niJMY1wAvx/ingress-attributes" + } + } + }, + "links": { + "self": "/api/v2/configuration-versions/cv-aaady7niJMY1wAvx" + } + } +} +``` + +## Upload Configuration Files for a Test + +`PUT https://archivist.terraform.io/v1/object/` + +**The URL is provided in the `upload-url` attribute when creating a `configuration-versions` resource. After creation, the URL is hidden on the resource and no longer available.** + +### Sample Request + +**@filename is the name of the configuration file you wish to upload.** + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @filename \ + https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da +``` + +## List Tests for a Module + +`GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module which the tests have executed against. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module which the tests have executed against. | +| `:provider` | The name of the provider which the tests have executed against. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not automatically encode URLs. + +| Parameter | Description | Required | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `page[number]` | If omitted, the endpoint returns the first page. | Optional | +| `page[size]` | If omitted, the endpoint returns 20 runs per page. | Optional | +| `filter[source]` | **Optional.** A comma-separated list of test sources; the result will only include tests that came from one of these sources. Options are listed in [Test Sources](/terraform/enterprise/api-docs/private-registry/tests#test-sources). | | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "trun-KFg8DSiRz4E37mdJ", + "type": "test-runs", + "attributes": { + "status": "finished", + "status-timestamps": { + "queued-at": "2023-10-03T18:27:39+00:00", + "started-at": "2023-10-03T18:27:41+00:00", + "finished-at": "2023-10-03T18:27:53+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv", + "created-at": "2023-10-03T18:27:39.239Z", + "updated-at": "2023-10-03T18:27:53.574Z", + "test-configurable-type": "RegistryModule", + "test-configurable-id": "mod-9rjVHLCUE9QD3k6L", + "variables": [ + { + "key": "number", + "value": "4" + } + ], + "filters": [ + "tests/test.tftest.hcl" + ], + "test-directory": "tests", + "verbose": true, + "test-status": "pass", + "tests-passed": 1, + "tests-failed": 0, + "tests-errored": 0, + "tests-skipped": 0, + "source": "tfe-api", + "message": "Queued manually via the Terraform Enterprise API" + }, + "relationships": { + "configuration-version": { + "data": { + "id": "cv-d3zBGFf5DfWY4GY9", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9" + } + }, + "created-by": { + "data": { + "id": "user-zsRFs3AGaAHzbEfs", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs" + } + } + } + }, + {...} + ] +} +``` + +## Get Test Details + +`GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module which the test was executed against. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module which the test was executed against. | +| `:provider` | The name of the provider which the test was executed against. | +| `:test_run_id` | The test ID to get. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7 +``` + +### Sample Response + +```json +{ + "data": { + "id": "trun-KFg8DSiRz4E37mdJ", + "type": "test-runs", + "attributes": { + "status": "finished", + "status-timestamps": { + "queued-at": "2023-10-03T18:27:39+00:00", + "started-at": "2023-10-03T18:27:41+00:00", + "finished-at": "2023-10-03T18:27:53+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv", + "created-at": "2023-10-03T18:27:39.239Z", + "updated-at": "2023-10-03T18:27:53.574Z", + "test-configurable-type": "RegistryModule", + "test-configurable-id": "mod-9rjVHLCUE9QD3k6L", + "variables": [ + { + "key": "number", + "value": "4" + } + ], + "filters": [ + "tests/test.tftest.hcl" + ], + "test-directory": "tests", + "verbose": true, + "test-status": "pass", + "tests-passed": 1, + "tests-failed": 0, + "tests-errored": 0, + "tests-skipped": 0, + "source": "tfe-api", + "message": "Queued manually via the Terraform Enterprise API" + }, + "relationships": { + "configuration-version": { + "data": { + "id": "cv-d3zBGFf5DfWY4GY9", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9" + } + }, + "created-by": { + "data": { + "id": "user-zsRFs3AGaAHzbEfs", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs" + } + } + } + } +} +``` + +## Cancel a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id/cancel` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to create a test in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the test is being canceled. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test is being canceled. | +| `:provider` | The name of the provider for which the test is being canceled. | +| `:test_run_id` | The test ID to cancel. | + +Use the `cancel` action to interrupt a test that is currently running. The action sends an `INT` signal to the running Terraform process, which instructs Terraform to safely end the tests and attempt to teardown any infrastructure that your tests create. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------ | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Test was not running; cancel not allowed. | +| [404][] | [JSON API error object][] | Test was not found or user not authorized. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7/cancel +``` + +## Forcefully cancel a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id/force-cancel` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The namespace of the module for which the test is being force-canceled. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test is being force-canceled. | +| `:provider` | The name of the provider for which the test is being force-canceled. | +| `:test_run_id` | The test ID to cancel. | + +The `force-cancel` action ends the test immediately. Once invoked, Terraform places the test into a `canceled` state and terminates the running Terraform process. + +~> **Warning:** This endpoint has potentially dangerous side-effects, including loss of any in-flight state in the running Terraform process. Use this operation with extreme caution. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Test was not running, or has not been canceled non-forcefully. | +| [404][] | [JSON API error object][] | Test was not found or user not authorized. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7/force-cancel +``` + +## Create an Environment Variable for Module Tests + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization of the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the testing environment variable is being created. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the testing environment variable is being created. | +| `:provider` | The name of the provider for which the testing environment variable is being created. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"vars"`. | +| `data.attributes.key` | string | none | The variable's name. Test variable keys must begin with a letter or underscore and can only contain letters, numbers, and underscores. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | none | The description of the variable. | +| `data.attributes.category` | string | none | This must be `"env"`. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. When set to `true`, Terraform writes the variable once and is not visible thereafter. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "category":"env", + "sensitive":false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars +``` + +### Sample Response + + { + "data": { + "id": "var-xSCUzCxdqMs2ygcg", + "type": "vars", + "attributes": { + "key": "keykey", + "value": "some_value", + "sensitive": false, + "category": "env", + "hcl": false, + "created-at": "2023-10-03T19:47:05.393Z", + "description": "some description", + "version-id": "699b14ea5d5e5c02f6352fac6bfd0a1424c21d32be14d1d9eb79f5e1f28f663a" + }, + "links": { + "self": "/api/v2/vars/var-xSCUzCxdqMs2ygcg" + } + } + } + +## List Test Variables for a Module + +`GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The namespace of the module which the test environment variables were created for. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module which the test environment variables were created for. | +| `:provider` | The name of the provider which the test environment variables were created for. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "var-xSCUzCxdqMs2ygcg", + "type": "vars", + "attributes": { + "key": "keykey", + "value": "some_value", + "sensitive": false, + "category": "env", + "hcl": false, + "created-at": "2023-10-03T19:47:05.393Z", + "description": "some description", + "version-id": "699b14ea5d5e5c02f6352fac6bfd0a1424c21d32be14d1d9eb79f5e1f28f663a" + }, + "links": { + "self": "/api/v2/vars/var-xSCUzCxdqMs2ygcg" + } + } + ] +} +``` + +## Update Test Variables for a Module + +`PATCH /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars/variable_id` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the test environment variable is being updated. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test environment variable is being updated. | +| `:provider` | The name of the provider for which the test environment variable is being updated. | +| `:variable_id` | The ID of the variable to update. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes` | object | none | New attributes for the variable. This object can include `key`, `value`, `description`, `category`, and `sensitive` properties. Refer to [Create an Environment Variable for Module Tests](#create-an-environment-variable-for-module-tests) for additional information. All properties are optional. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "key":"name", + "value":"mars", + "description": "new description", + "category":"env", + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "description":"new description", + "sensitive":false, + "category":"env", + "hcl":false + } + } +} +``` + +## Delete Test Variable for a Module + +`DELETE /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars/variable_id` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The namespace of the module for which the test environment variable is being deleted. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test environment variable is being deleted. | +| `:provider` | The name of the provider for which the test environment variable is being deleted. | +| `:variable_id` | The ID of the variable to delete. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars/var-yRmifb4PJj7cLkMG +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/project-team-access.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/project-team-access.mdx new file mode 100644 index 0000000000..e77d497747 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/project-team-access.mdx @@ -0,0 +1,523 @@ +--- +page_title: /team-projects API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/team-projects` endpoint to read, add, + update, and remove team access from a project. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Project team access API reference + + + +-> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing). + + + +The team access APIs are used to associate a team to permissions on a project. A single `team-project` resource contains the relationship between the Team and Project, including the privileges the team has on the project. + +## Resource permissions + +A `team-project` resource represents a team's local permissions on a specific project. Teams can also have organization-level permissions that grant access to projects. HCP Terraform uses the more restrictive access level. For example, a team with the **Manage projects** permission enabled has admin access on all projects, even if their `team-project` on a particular project only grants read access. For more information, refer to [Managing Project Access](/terraform/enterprise/users-teams-organizations/teams/manage#managing-project-access). + +Any member of an organization can view team access relative to their own team memberships, including secret teams of which they are a member. Organization owners and project admins can modify team access or view the full set of secret team accesses. The organization token and the owners team token can act as an owner on these endpoints. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +## Project Team Access Levels + +| Access Level | Description | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `read` | Read project and Read workspace access role on project workspaces | +| `write` | Read project and Write workspace access role on project workspaces | +| `maintain` | Read project and Admin workspace access role on project workspaces | +| `admin` | Admin project, Admin workspace access role on project workspaces, create workspaces within project, move workspaces between projects, manage project team access | +| `custom` | Custom access permissions on project and project's workspaces | + +## List Team Access to a Project + +`GET /team-projects` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Project not found or user unauthorized to perform action | + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). + +| Parameter | Description | +| --------------------- | ----------------------------------------------------- | +| `filter[project][id]` | **Required.** The project ID to list team access for. | +| `page[number]` | **Optional.** | +| `page[size]` | **Optional.** | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tprj-TLznAnYdcsD2Dcmm", + "type": "team-projects", + "attributes": { + "access": "read", + "project-access": { + "settings": "read", + "teams": "none" + }, + "workspace-access": { + "create": false, + "move": false, + "locking": false, + "delete": false, + "runs": "read", + "variables": "read", + "state-versions": "read", + "sentinel-mocks": "none", + "run-tasks": false + } + }, + "relationships": { + "team": { + "data": { + "id": "team-KpibQGL5GqRAWBwT", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-KpibQGL5GqRAWBwT" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-TLznAnYdcsD2Dcmm" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a Team Access relationship + +`GET /team-projects/:id` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Team access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/project relationship. Obtain this from the [list team access action](#list-team-access-to-a-project) described above. | + +As mentioned in [Add Team Access to a Project](#add-team-access-to-a-project) and [Update to a Project](#update-team-access-to-a-project), several permission attributes are not editable unless you set `access` to `custom`. If you set `access` to `read`, `plan`, `write`, or `admin`, certain attributes are read-only and reflect the _implicit permissions_ granted to the current access level. + +For example, if you set `access` to `read`, the implicit permission level for project settings and workspace run is "read". Conversely, if you set the access level to `admin`, the implicit permission level for the project settings is "delete", while the workspace runs permission is "apply". + +Several permission attributes are not editable unless `access` is set to `custom`. When access is `read`, `plan`, `write`, or `admin`, these attributes are read-only and reflect the implicit permissions granted to the current access level. + +For example, when access is `read`, the implicit level for the project settings and workspace runs permissions are "read". Conversely, when the access level is `admin`, the implicit level for the project settings is "delete" and the workspace runs permission is "apply". To see all of the implied permissions at different access levels, see [Implied Custom Permission Levels](#implied-custom-permission-levels). + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/team-projects/tprj-s68jV4FWCDwWvQq8 +``` + +### Sample Response + +```json +{ + "data": { + "id": "tprj-TLznAnYdcsD2Dcmm", + "type": "team-projects", + "attributes": { + "access": "read", + "project-access": { + "settings": "read", + "teams": "none" + }, + "workspace-access": { + "create": false, + "move": false, + "locking": false, + "delete": false, + "runs": "read", + "variables": "read", + "state-versions": "read", + "sentinel-mocks": "none", + "run-tasks": false + } + }, + "relationships": { + "team": { + "data": { + "id": "team-KpibQGL5GqRAWBwT", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-KpibQGL5GqRAWBwT" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-TLznAnYdcsD2Dcmm" + } + } +} +``` + +## Add Team Access to a Project + +`POST /team-projects` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ---------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Project or Team not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"team-projects"`. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `write`, `maintain`, `admin`, or `custom`. | +| `data.relationships.project.data.type` | string | | Must be `projects`. | +| `data.relationships.project.data.id` | string | | The project ID to which the team is to be added. | +| `data.relationships.team.data.type` | string | | Must be `teams`. | +| `data.relationships.team.data.id` | string | | The ID of the team to add to the project. | +| `data.attributes.project-access.settings` | string | "read" | If `access` is `custom`, the permission to grant for the project's settings. Can only be used when `access` is `custom`. Valid values include `read`, `update`, or `delete`. | +| `data.attributes.project-access.teams` | string | "none" | If `access` is `custom`, the permission to grant for the project's teams. Can only be used when `access` is `custom`. Valid values include `none`, `read`, or `manage`. | +| `data.attributes.workspace-access.runs` | string | "read" | If `access` is `custom`, the permission to grant for the project's workspaces' runs. Can only be used when `access` is `custom`. Valid values include `read`, `plan`, or `apply`. | +| `data.attributes.workspace-access.sentinel-mocks` | string | "none" | If `access` is `custom`, the permission to grant for the project's workspaces' Sentinel mocks. Can only be used when `access` is `custom`. Valid values include `none`, or `read`. | +| `data.attributes.workspace-access.state-versions` | string | "none" | If `access` is `custom`, the permission to grant for the project's workspaces state versions. Can only be used when `access` is `custom`. Valid values include `none`, `read-outputs`, `read`, or `write`. | +| `data.attributes.workspace-access.variables` | string | "none" | If `access` is `custom`, the permission to grant for the project's workspaces' variables. Can only be used when `access` is `custom`. Valid values include `none`, `read`, or `write`. | +| `data.attributes.workspace-access.create` | boolean | false | If `access` is `custom`, this permission allows the team to create workspaces in the project. | +| `data.attributes.workspace-access.locking` | boolean | false | If `access` is `custom`, the permission granting the ability to manually lock or unlock the project's workspaces. Can only be used when `access` is `custom`. | +| `data.attributes.workspace-access.delete` | boolean | false | If `access` is `custom`, the permission granting the ability to delete the project's workspaces. Can only be used when `access` is `custom`. | +| `data.attributes.workspace-access.move` | boolean | false | If `access` is `move`, this permission allows the team to move workspaces into and out of the project. The team must also have permissions to the project(s) receiving the the workspace(s). | +| `data.attributes.workspace-access.run-tasks` | boolean | false | If `access` is `custom`, this permission allows the team to manage run tasks within the project's workspaces. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "access": "read" + }, + "relationships": { + "project": { + "data": { + "type": "projects", + "id": "prj-ckZoJwdERaWcFHwi" + } + }, + "team": { + "data": { + "type": "teams", + "id": "team-xMGyoUhKmTkTzmAy" + } + } + }, + "type": "team-projects" + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/team-projects +``` + +### Sample Response + +```json +{ + "data": { + "id": "tprj-WbG7p5KnT7S7HZqw", + "type": "team-projects", + "attributes": { + "access": "read", + "project-access": { + "settings": "read", + "teams": "none" + }, + "workspace-access": { + "create": false, + "move": false, + "locking": false, + "runs": "read", + "variables": "read", + "state-versions": "read", + "sentinel-mocks": "none", + "run-tasks": false + } + }, + "relationships": { + "team": { + "data": { + "id": "team-xMGyoUhKmTkTzmAy", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-xMGyoUhKmTkTzmAy" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw" + } + } +} +``` + +## Update Team Access to a Project + +`PATCH /team-projects/:id` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +| Parameter | | | Description | +| ------------------------ | ------ | - | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | | | The ID of the team/project relationship. Obtain this from the [list team access action](#list-team-access-to-a-project) described above. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `write`, `maintain`, `admin`, or `custom`. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw +``` + +### Sample Payload + +```json +{ + "data": { + "id": "tprj-WbG7p5KnT7S7HZqw", + "attributes": { + "access": "custom", + "project-access": { + "settings": "delete" + "teams": "manage", + }, + "workspace-access" : { + "runs": "apply", + "sentinel-mocks": "read", + "state-versions": "write", + "variables": "write", + "create": true, + "locking": true, + "delete": true, + "move": true, + "run-tasks": true + } + } + } +} +``` + +### Sample Response + +```json +{ + "data": { + "id": "tprj-WbG7p5KnT7S7HZqw", + "type": "team-projects", + "attributes": { + "access": "custom", + "project-access": { + "settings": "delete" + "teams": "manage", + }, + "workspace-access" : { + "runs": "apply", + "sentinel-mocks": "read", + "state-versions": "write", + "variables": "write", + "create": true, + "locking": true, + "delete": true, + "move": true, + "run-tasks": true + } + }, + "relationships": { + "team": { + "data": { + "id": "team-xMGyoUhKmTkTzmAy", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-xMGyoUhKmTkTzmAy" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw" + } + } +} +``` + +## Remove Team Access from a Project + +`DELETE /team-projects/:id` + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | | The Team Access was successfully destroyed | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/project relationship. Obtain this from the [list team access action](#list-team-access-to-a-project) described above. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw +``` + +## Implied Custom Permission Levels + +As mentioned above, when setting team access levels (`read`, `write`, `maintain`, or `admin`), you can individually set the following permissions if you use the `custom` access level. +The below table lists each access level alongside its implicit custom permission level. If you use the `custom` access level and do not specify a certain permission's level, that permission uses the default value listed below. + +| Permissions | `read` | `write` | `maintain` | `admin ` | `custom` default | +| ------------------------------- | ------ | ------- | ---------- | -------- | ---------------- | +| project-access.settings | "read" | "read" | "read" | "delete" | "read" | +| project-access.teams | "none" | "none" | "none" | "manage" | "none" | +| workspace-access.runs | "read" | "apply" | "apply" | "apply" | "read" | +| workspace-access.sentinel-mocks | "none" | "read" | "read" | "read" | "none" | +| workspace-access.state-versions | "read" | "write" | "write" | "write" | "none" | +| workspace-access.variables | "read" | "write" | "write" | "write" | "none" | +| workspace-access.create | false | false | true | true | false | +| workspace-access.locking | false | true | true | true | false | +| workspace-access.delete | false | false | true | true | false | +| workspace-access.move | false | false | false | true | false | +| workspace-access.run-tasks | false | false | true | true | false | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/projects.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/projects.mdx new file mode 100644 index 0000000000..211c0b3ee0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/projects.mdx @@ -0,0 +1,719 @@ +--- +page_title: /projects API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/projects` endpoint to list, show, create, + update, and delete an organization's projects. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[speculative plans]: /terraform/enterprise/run/remote-operations#speculative-plans + +# Projects API reference + +This topic provides reference information about the projects API. + +The scope of the API includes the following endpoints: + +| Method | Path | Action | +| -------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `POST` | `/organizations/:organization_name/projects` | Call this endpoint to [create a project](#create-a-project). | +| `PATCH` | `/projects/:project_id` | Call this endpoint to [update an existing project](#update-a-project). | +| `GET` | `/organizations/:organization_name/projects` | Call this endpoint to [list existing projects](#list-projects). | +| `GET` | `/projects/:project_id` | Call this endpoint to [show project details](#show-project). | +| `DELETE` | `/projects/:project_id` | Call this endpoint to [delete a project](#delete-a-project). | +| `GET` | `/projects/:project_id/tag-bindings` | Call this endpoint to [list project tag bindings](#list-project-tag-bindings). (For projects, this returns the same result set as the `effective-tag-bindings` endpoint.) | +| `GET` | `/projects/:project_id/effective-tag-bindings` | Call this endpoint to [list project effective tag bindings](#list-project-tag-bindings). (For projects, this returns the same result set as the `tag-bindings` endpoint.) | + +## Requirements + +You must be on a team with one of the **Owners** or **Manage projects** permissions settings enabled to create and manage projects. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +You can also provide an organization API token to call project API endpoints. Refer to [Organization API Tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) for additional information. + +## Create a Project + +`POST /organizations/:organization_name/projects` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create the project in. The organization must already exist in the system, and the user must have permissions to create new projects. | + +-> **Note:** Project creation is restricted to the owners team, teams with the "Manage Projects" permission, and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"projects"`. | +| `data.attributes.name` | string | | The name of the project. The name can contain letters, numbers, spaces, `-`, and `_`, but cannot start or end with spaces. It must be at least three characters long and no more than 40 characters long. | +| `data.attributes.description` | string | none | Optional. The description of the project. It must be no more than 256 characters long. | +| `data.attributes.auto-destroy-activity-duration` | string | none | Specifies the default for how long each workspace in the project should wait before automatically destroying its infrastructure. You can specify a duration up to four digits that is greater than `0` followed by either a `d` for days or `h` hours. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. All future workspaces in this project inherit this default value. Refer to [Automatically destroy inactive workspaces](/terraform/enterprise/projects/managing#automatically-destroy-inactive-workspaces) for additional information. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to bind to the project. Workspaces inherit the tags bound to their project. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "Test Project", + "description": "An example project for documentation.", + }, + "type": "projects", + "relationships": { + "tag-bindings": { + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "environment", + "value": "development" + } + }, + ] + } + } + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/projects +``` + +### Sample Response + +```json +{ + "data": { + "id": "prj-WsVcWRr7SfxRci1v", + "type": "projects", + "attributes": { + "name": "Test Project", + "description": "An example project for documentation.", + "permissions": { + "can-update": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v" + } + } +} +``` + +## Update a Project + +Call the following endpoint to update a project: + +`PATCH /projects/:project_id` + +| Parameter | Description | +| ------------- | ------------------------------- | +| `:project_id` | The ID of the project to update | + +### Request Body + +These PATCH endpoints require a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"projects"`. | +| `data.attributes.name` | string | existing value | A new name for the project. The name can contain letters, numbers, spaces, `-`, and `_`, but cannot start or end with spaces. It must be at least 3 characters long and no more than 40 characters long. | +| `data.attributes.description` | string | existing value | The new description for the project. It must be no more than 256 characters long. | +| `data.attributes.auto-destroy-activity-duration` | string | none | Specifies how long each workspace in the project should wait before automatically destroying its infrastructure by default. You can specify a duration up to four digits that is greater than `0` followed by either a `d` for days or `h` hours. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. When you update this value, all workspaces in the project receive the new value unless you previously configured an override. Refer to [Automatically destroy inactive workspaces](/terraform/enterprise/projects/managing#automatically-destroy-inactive-workspaces) for additional information. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to bind to the project. Workspaces inherit the tags bound to their project. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "Infrastructure Project" + }, + "type": "projects", + "relationships": { + "tag-bindings": { + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "environment", + "value": "staging" + } + } + ] + } + } + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v +``` + +### Sample Response + +```json +{ + "data": { + "id": "prj-WsVcWRr7SfxRci1v", + "type": "projects", + "attributes": { + "name": "Infrastructure Project", + "description": null, + "workspace-count": 4, + "team-count": 2, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v" + } + } +} +``` + +## List projects + +This endpoint lists projects in the organization. + +`GET /organizations/:organization_name/projects` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------- | +| `:organization_name` | The name of the organization to list the projects of. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 projects per page. | +| `q` | **Optional.** A search query string. This query searches projects by name. This search is case-insensitive. If both `q` and `filter[names]` are specified, `filter[names]` will be used. | +| `filter[names]` | **Optional.** If specified, returns the project with the matching name. This filter is case-insensitive. If multiple comma separated values are specified, projects matching any of the names are returned. | +| `filter[permissions][create-workspace]` | **Optional.** If present, returns a list of projects that the authenticated user can create workspaces in. | +| `filter[permissions][update]` | **Optional.** If present, returns a list of projects that the authenticated user can update. | +| `sort` | **Optional.** Allows sorting the organization's projects by `"name"`. Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable. | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/projects +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "prj-W6k9K23oSXRHGpj3", + "type": "projects", + "attributes": { + "name": "Default Project", + "description": null, + "workspace-count": 2, + "team-count": 1, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-W6k9K23oSXRHGpj3" + } + }, + { + "id": "prj-YoriCxAawTMDLswn", + "type": "projects", + "attributes": { + "name": "Infrastructure Project", + "description": null, + "workspace-count": 4, + "team-count": 2, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-YoriCxAawTMDLswn" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "status-counts": { + "total": 2, + "matching": 2 + }, + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show project + +`GET /projects/:project_id` + +| Parameter | Description | +| ------------- | -------------- | +| `:project_id` | The project ID | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v +``` + +### Sample Response + +```json +{ + "data": { + "id": "prj-WsVcWRr7SfxRci1v", + "type": "projects", + "attributes": { + "name": "Infrastructure Project", + "description": null, + "workspace-count": 4, + "team-count": 2, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + }, + "auto-destroy-activity-duration": "2d" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v" + } + } +} +``` + +## Delete a project + +A project cannot be deleted if it contains stacks or workspaces. + +`DELETE /projects/:project_id` + +| Parameter | Description | +| ------------- | ------------------------------- | +| `:project_id` | The ID of the project to delete | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the project | +| [403][] | [JSON API error object][] | Not authorized to perform a force delete on the project | +| [404][] | [JSON API error object][] | Project not found, or user unauthorized to perform project delete | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v +``` + +## List project tag bindings + +Call the following endpoints to list the tags bound to a project. + +- `GET /projects/:project_id/tag-bindings`: Lists the set of tags associated with the project. Tags set on the project are inherited by its workspaces. + +| Parameter | Description | +| ------------- | ---------------------- | +| `:project_id` | The ID of the project. | + +### Sample request + +The following request returns all tags bound to a project with the ID +`prj-WsVcWRr7SfxRci1v`. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings +``` + +### Sample response + +```json +{ + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "added", + "value": "new", + "created-at": "2024-11-20T00:04:47.948Z" + } + }, + { + "type": "tag-bindings", + "attributes": { + "key": "aww", + "value": "aww", + "created-at": "2024-11-20T00:04:47.948Z" + } + } + ] +} +``` + +## Add or update tag bindings on a project + +This endpoint can be used to add key-value Tag Bindings to an existing resource, or to update +existing Tag Binding values on the resource. It cannot be used to remove any tag bindings from the resource. +This endpoint is useful when you want to ensure a modification is additive. + +Tag Bindings have special constraints: + +- Up to 10 tags can be applied to a project +- All workspaces belonging to the project will inherit the Tag Bindings applied to this project. +- Keys must be no more than 128 characters, allowing all alphanumeric characters plus the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. +- Values allow the same characters, but can be up to 256 characters. +- Certain key prefixes, including `hc:` and `hcp:` are not allowed. + +`PATCH /projects/:project_id/tag-bindings` + +| Parameter | Description | +| ------------- | ------------------------------- | +| `:project_id` | The ID of the project to update | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that for each data item, `type`, as well as `attributes.key` is required. + +| Key path | Type | Default | Description | +| ------------------------- | ------ | ------- | ------------------------------------- | +| `data[].type` | string | | Must be `"tag-bindings"`. | +| `data[].attributes.key` | string | | The key of the tag to add or update. | +| `data[].attributes.value` | string | | The name of the tag to add or update. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/projects/prj-82d2281aa259ba09/tag-bindings +``` + +### Sample Response + +Example status code 200 response after updating tag bindings: + + + +```json +{ + "data": [ + { + "id": "tb-e4a5847b2cf06559", + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "id": "tb-97ce954636f93a6c", + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + + + +## Move workspaces into a project + +This endpoint allows you to move one or more workspaces into a project. You must have permission to move workspaces on +the destination project as well as any source project(s). If you are not authorized to move any of the workspaces in the +request, or if any workspaces in the request are not found, then no workspaces will be moved. + +`POST /projects/:project_id/relationships/workspaces` + +| Parameter | Description | +| ------------- | --------------------------------- | +| `:project_id` | The ID of the destination project | + +This POST endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ---------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"` | +| `data[].id` | string | | The ids of workspaces to move into the destination project | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | +| [204][] | No Content | Successfully moved workspace(s) | +| [403][] | [JSON API error object][] | Workspace(s) not found, or user is not authorized to move all workspaces out of their current project(s) | +| [404][] | [JSON API error object][] | Project not found, or user unauthorized to move workspaces into project | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-AQEct2XFuH4HBsmS" + } + ] +} + +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/projects/prj-zXm4y2BjeGPgHtkp/relationships/workspaces +``` + +### Sample Error Response + +```json +{ + "errors": [ + { + "status": "403", + "title": "forbidden", + "detail": "Workspace(s) not found, or you are not authorized to move them: ws-AQEct2XFuH4HBmS" + } + ] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/reserved-tag-keys.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/reserved-tag-keys.mdx new file mode 100644 index 0000000000..51655fd031 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/reserved-tag-keys.mdx @@ -0,0 +1,271 @@ +--- +page_title: /reserved-tag-keys API reference for Terraform Enterprise +description: >- + Use the `/reserved-tag-keys` API endpoints to reserve tag keys that have + special meaning for your organization. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[speculative plans]: /terraform/enterprise/run/remote-operations#speculative-plans + +# Reserved tag keys API reference + +Use the `/reserved-tag-keys` API endpoints to define and manage tag keys that +have special meaning for your organization. Reserving tag keys enable project +and workspace managers to follow a consistent tagging strategy across the +organization. You can also use them to provide project managers with a means of +disabling overrides for inherited tags. + +The following table describes the available endpoints: + +| Method | Path | Description | +| -------- | ----------------------------------------------------- | --------------------------------------------------------------------------------- | +| `GET` | `/organizations/:organization_name/reserved-tag-keys` | [List reserved tag keys](#list-reserved-tag-keys) for the specified organization. | +| `POST` | `/organizations/:organization_name/reserved-tag-keys` | [Add a reserved tag key](#add-a-reserved-tag-key) to the specified organization. | +| `PATCH` | `/reserved-tags/:reserved_tag_key_id` | [Update a reserved tag key](#add-a-reserved-tag-value) with the specified ID. | +| `DELETE` | `/reserved-tags/:reserved_tag_key_id` | [Delete a reserved tag key](#delete-a-reserved-tag-key) with the specified ID. | + +## Path parameters + +The `/reserved-tag-keys/` API endpoints require the following path parameters: + +| Parameter | Description | +| ---------------------- | ---------------------------------------------------------- | +| `:reserved_tag_key_id` | The external ID of the reserved tag key. | +| `:organization_name` | The name of the organization containing the reserved tags. | + +## List reserved tag keys + +`GET /organizations/:organization_name/reserved-tag-keys` + +### Sample payload + +This endpoint does not require a payload. + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys +``` + +### Sample response + +```json +{ + "data": [ + { + "id": "rtk-jjnTseo8NN1jACbk", + "type": "reserved-tag-keys", + "attributes": { + "key": "environment", + "disable-overrides": false, + "created-at": "2024-08-13T23:06:42.523Z", + "updated-at": "2024-08-13T23:06:42.523Z" + } + }, + { + "id": "rtk-F1s7kKUShAQxhA1b", + "type": "reserved-tag-keys", + "attributes": { + "key": "cost-center", + "disable-overrides": false, + "created-at": "2024-08-13T23:06:51.445Z", + "updated-at": "2024-08-13T23:06:51.445Z" + } + }, + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} + +``` + +## Create a reserved tag key + +`POST /organizations/:organization_name/reserved-tag-keys` + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------ | ------- | ------- | --------------------------------- | +| `data.type` | string | none | Must be `reserved-tag-keys`. | +| `data.attributes.key` | string | none | The key targeted by this reserved | +| tag key. | | | | +| `data.attributes.disable-overrides` | boolean | none | If `true`, disables | +| overriding inherited tags with the specified key at the workspace level. | | | | + +### Sample payload + +```json +{ + "data": { + "type": "reserved-tag-keys", + "attributes": { + "key": "environment", + "disable-overrides": false + } + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/${ORGANIZATION_NAME}/reserved-tag-keys +``` + +### Sample response + +```json +{ + "data": { + "id": "rtk-Tj86UdGahKGDiYXY", + "type": "reserved-tag-keys", + "attributes": { + "key": "environment", + "disable-overrides": false, + "created-at": "2024-09-04T05:02:06.794Z", + "updated-at": "2024-09-04T05:02:06.794Z" + } + } +} +``` + +## Update a reserved tag key + +`PATCH /reserved-tags/:reserved_tag_key_id` + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------ | ------- | ------- | --------------------------------- | +| `data.type` | string | none | Must be `reserved-tag-keys`. | +| `data.attributes.key` | string | none | The key targeted by this reserved | +| tag key. | | | | +| `data.attributes.disable-overrides` | boolean | none | If `true`, disables | +| overriding inherited tags with the specified key at the workspace level. | | | | + +### Sample payload + +```json +{ + "data": { + "id": "rtk-Tj86UdGahKGDiYXY", + "type": "reserved-tag-keys", + "attributes": { + "key": "env", + "disable-overrides": true, + "created-at": "2024-09-04T05:02:06.794Z", + "updated-at": "2024-09-04T05:02:06.794Z" + } + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + https://app.terraform.io/api/v2/reserved-tags/${RESERVED_TAG_ID} +``` + +### Sample response + +```json +{ + "data": { + "id": "rtk-zMtWLDftAjY3b5pA", + "type": "reserved-tag-keys", + "attributes": { + "key": "env", + "disable-overrides": true, + "created-at": "2024-09-04T05:05:10.449Z", + "updated-at": "2024-09-04T05:05:13.486Z" + } + } +} +``` + +## Delete a reserved tag key + +`DELETE /reserved-tags/:reserved_tag_key_id` + +### Sample payload + +This endpoint does not require a payload. + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/reserved-tags/rtk-zMtWLDftAjY3b5pA +``` + +### Sample response + +This endpoint does not return a response body. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-task-stages-and-results.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-task-stages-and-results.mdx new file mode 100644 index 0000000000..40c8a1f250 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-task-stages-and-results.mdx @@ -0,0 +1,366 @@ +--- +page_title: /task-stages API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/task-stages` endpoint to read run tasks + and their results, and override run task stages. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API documents]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[run]: /terraform/enterprise/run/states + +# Run task stages and results API reference + +HCP Terraform uses run task stages and run task results to track [run task](/terraform/enterprise/workspaces/settings/run-tasks) execution. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +When HCP Terraform creates a [run][], it reads the run tasks associated to the workspace. Each run task in the workspace is configured to begin during a specific [run stage](/terraform/enterprise/run/states). HCP Terraform creates a run task stage object for each run stage that triggers run tasks. You can configure run tasks during the [Pre-Plan Stage](/terraform/enterprise/run/states#the-pre-plan-stage), [Post-Plan Stage](/terraform/enterprise/run/states#the-post-plan-stage), [Pre-Apply Stage](/terraform/enterprise/run/states#the-pre-apply-stage) and [Post-Apply Stage](/terraform/enterprise/run/states#the-post-apply-stage). + +Run task stages then create a run task result for each run task. For example, a workspace has two run tasks called `alpha` and `beta`. For each run, HCP Terraform creates one run task stage called `post-plan`. That run task stage has two run task results: one for the `alpha` run task and one for the `beta` run task. + +This page lists the endpoints to retrieve run task stages and run task results. Refer to the [Run Tasks API](/terraform/enterprise/api-docs/run-tasks/run-tasks) for endpoints to create and manage run tasks within HCP Terraform. Refer to the [Run Tasks Integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) for endpoints to build custom run tasks for the HCP Terraform ecosystem. + +## Attributes + +### Run Task Stage Status + +The run task stage status is found in `data.attributes.status`, and you can reference the following list of possible values. + +| Status | Description | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `pending` | The initial status of a run task stage after creation. | +| `running` | The run task stage is executing one or more tasks, which have not yet completed. | +| `passed` | All of the run task results in the stage passed. | +| `failed` | One more results in the run task stage failed. | +| `awaiting_override` | The task stage is waiting for user input. Once a user manually overrides the failed run tasks, the run returns to the `running` state. | +| `errored` | The run task stage has errored. | +| `canceled` | The run task stage has been canceled. | +| `unreachable` | The run task stage could not be executed. | + +### Run Task Result Status + +The run task result status is found in `data.attributes.status`, and you can reference the following list of possible values. + +| Status | Description | +| ------------- | --------------------------------------------------------------------- | +| `pending` | The initial status of a run task result after creation. | +| `running` | The associated run task is begun execution and has not yet completed. | +| `passed` | The associated run task executed and returned a passing result. | +| `failed` | The associated run task executed and returned a failed result. | +| `errored` | The associated run task has errored during execution. | +| `canceled` | The associated run task execution has been canceled. | +| `unreachable` | The associated run task could not be executed. | + +## List the Run Task Stages in a Run + +`GET /runs/:run_id/task-stages` + +| Parameter | Description | +| --------- | ----------------------------------- | +| `run_id` | The run ID to list task stages for. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------- | +| [200][] | Array of [JSON API documents][] (`type: "task-stages"`) | Successfully listed task-stages | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/runs/run-XdgtChJuuUwLoSmw/task-stages +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ts-rL5ZsuwfjqfPJcdi", + "type": "task-stages", + "attributes": { + "status": "passed", + "stage": "post_plan", + "status-timestamps": { + "passed-at": "2022-06-08T20:32:12+08:00", + "running-at": "2022-06-08T20:32:11+08:00" + }, + "created-at": "2022-06-08T12:31:56.94Z", + "updated-at": "2022-06-08T12:32:12.315Z" + }, + "relationships": { + "run": { + "data": { + "id": "run-XdgtChJuuUwLoSmw", + "type": "runs" + } + }, + "task-results": { + "data": [ + { + "id": "taskrs-EmnmsEDL1jgd1GTP", + "type": "task-results" + } + ] + }, + "policy-evaluations":{ + "data":[ + { + "id":"poleval-iouaha9KLgGWkBRQ", + "type":"policy-evaluations" + } + ] + } + }, + "links": { + "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi" + } + } + ] +} +``` + +## Show a Run Task Stage + +`GET /task-stages/:task_stage_id` + +| Parameter | Description | +| ---------------- | ----------------------------- | +| `:task_stage_id` | The run task stage ID to get. | + +This endpoint shows details of a specific task stage. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ------------------------------------------- | +| [200][] | [JSON API document][] (`type: "task-stages"`) | Success | +| [404][] | [JSON API error object][] | Task stage not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi +``` + +### Sample Response + +```json +{ + "data": { + "id": "ts-rL5ZsuwfjqfPJcdi", + "type": "task-stages", + "attributes": { + "status": "passed", + "stage": "post_plan", + "status-timestamps": { + "passed-at": "2022-06-08T20:32:12+08:00", + "running-at": "2022-06-08T20:32:11+08:00" + }, + "created-at": "2022-06-08T12:31:56.94Z", + "updated-at": "2022-06-08T12:32:12.315Z" + }, + "relationships": { + "run": { + "data": { + "id": "run-XdgtChJuuUwLoSmw", + "type": "runs" + } + }, + "task-results": { + "data": [ + { + "id": "taskrs-EmnmsEDL1jgd1GTP", + "type": "task-results" + } + ] + }, + "policy-evaluations":{ + "data":[ + { + "id":"poleval-iouaha9KLgGWkBRQ", + "type":"policy-evaluations" + } + ] + } + }, + "links": { + "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi" + } + } +} +``` + +## Show a Run Task Result + +`GET /task-results/:task_result_id` + +| Parameter | Description | +| ----------------- | ------------------------------ | +| `:task_result_id` | The run task result ID to get. | + +This endpoint shows the details for a specific run task result. + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------- | +| [200][] | [JSON API document][] (`type: "task-results"`) | Success | +| [404][] | [JSON API error object][] | Task result not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/task-results/taskrs-EmnmsEDL1jgd1GZz +``` + +### Sample Response + +```json +{ + "data": { + "id": "taskrs-EmnmsEDL1jgd1GZz", + "type": "task-results", + "attributes": { + "message": "No issues found.\nSeverity threshold is set to low.", + "status": "passed", + "status-timestamps": { + "passed-at": "2022-06-08T20:32:12+08:00", + "running-at": "2022-06-08T20:32:11+08:00" + }, + "url": "https://external.service/project/task-123abc", + "created-at": "2022-06-08T12:31:56.954Z", + "updated-at": "2022-06-08T12:32:12.27Z", + "task-id": "task-b6MaHZmGopHDtqhn", + "task-name": "example-task", + "task-url": "https://external.service/task-123abc", + "stage": "post_plan", + "is-speculative": false, + "workspace-task-id": "wstask-258juqenQeWb3DZz", + "workspace-task-enforcement-level": "mandatory" + }, + "relationships": { + "task-stage": { + "data": { + "id": "ts-rL5ZsuwfjqfPJczZ", + "type": "task-stages" + } + } + }, + "links": { + "self": "/api/v2/task-results/taskrs-EmnmsEDL1jgd1GZz" + } + } +} +``` + +## Available Related Resources + +### Task Stage + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource | Description | +| -------------------- | ---------------------------------------------------------- | +| `run` | Information about the associated run. | +| `run.workspace` | Information about the associated workspace. | +| `task-results` | Information about the results for a task-stage. | +| `policy-evaluations` | Information about the policy evaluations for a task-stage. | + +## Override a Task Stage + +`POST /task-stages/:task_stage_id/actions/override` + +| Parameter | Description | +| ---------------- | ------------------------------------- | +| `:task_stage_id` | The ID of the task stage to override. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi/actions/override +``` + +### Sample Response + +```json +{ + "data":{ + "id":"ts-F7MumZQcJzVh1ZZk", + "type":"task-stages", + "attributes":{ + "status":"running", + "stage":"post_plan", + "status-timestamps":{ + "running-at":"2022-09-21T06:36:54+00:00", + "awaiting-override-at":"2022-09-21T06:31:50+00:00" + }, + "created-at":"2022-09-21T06:29:44.632Z", + "updated-at":"2022-09-21T06:36:54.952Z", + "permissions":{ + "can-override-policy":true, + "can-override-tasks":false, + "can-override":true + }, + "actions":{ + "is-overridable":false + } + }, + "relationships":{ + "run":{ + "data":{ + "id":"run-K6N4BAz8NfUyR2QB", + "type":"runs" + } + }, + "task-results":{ + "data":[ + + ] + }, + "policy-evaluations":{ + "data":[ + { + "id":"poleval-atNKxwvjYy4Gwk3k", + "type":"policy-evaluations" + } + ] + } + }, + "links":{ + "self":"/api/v2/task-stages/ts-F7MumZQcJzVh1ZZk" + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx new file mode 100644 index 0000000000..4a285f56e3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx @@ -0,0 +1,296 @@ +--- +page_title: Run tasks integration API for Terraform Enterprise +description: >- + Use Terraform Enterprise API's run task integration API to trigger run tasks + at specific run phases and learn how to read run task responses. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Run tasks integration API + +[Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. +This page lists the API endpoints used to trigger a run task and the expected response from the integration. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +Refer to [run tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks) for the API endpoints to create and manage run tasks within HCP Terraform. You can also access a complete list of all run tasks in the [Terraform Registry](https://registry.terraform.io/browse/run-tasks). + +## Run Task Request + +When a run reaches the appropriate phase and a run task is triggered, HCP Terraform will send a request to the run task's URL. +The service receiving the run task request should respond with `200 OK`, or HCP Terraform will retry to trigger the run task. + +`POST :url` + +| Parameter | Description | +| --------- | ------------------------------------------------------- | +| `:url` | The URL configured in the run task to send requests to. | + +| Status | Response | Reason | +| ------- | ---------- | --------------------------------- | +| [200][] | No Content | Successfully submitted a run task | + +### Request Body + +The POST request submits a JSON object with the following properties as a request payload. + +#### Common Properties + +All request payloads contain the following properties. + +| Key path | Type | Values | Description | +| ------------------------------------ | ------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `payload_version` | integer | `1` | Schema version of the payload. Only `1` is supported. | +| `stage` | string | `pre_plan`, `post_plan`, `pre_apply`, `post_apply` | The [run stage](/terraform/enterprise/run/states) when HCP Terraform triggers the run task. | +| `access_token` | string | | Bearer token to use when calling back to HCP Terraform. | +| `capabilities` | object | | A map of the capabilities that the caller supports. | +| `capabilities.outcomes` | bool | | A flag indicating the caller accepts detailed run task outcomes. | +| `configuration_version_download_url` | string | | The URL to [download the configuration version](/terraform/enterprise/api-docs/configuration-versions#download-configuration-files). This is `null` if the configuration version is not available to download. | +| `configuration_version_id` | string | | The ID of the [configuration version](/terraform/enterprise/api-docs/configuration-versions) for the run. | +| `is_speculative` | bool | | Whether the task is part of a [speculative run](/terraform/enterprise/run/remote-operations#speculative-plans). | +| `organization_name` | string | | Name of the organization the task is configured within. | +| `run_app_url` | string | | URL within HCP Terraform to the run. | +| `run_created_at` | string | | When the run was started. | +| `run_created_by` | string | | Who created the run. | +| `run_id` | string | | Id of the run this task is part of. | +| `run_message` | string | | Message that was associated with the run. | +| `task_result_callback_url` | string | | URL that should called back with the result of this task. | +| `task_result_enforcement_level` | string | `mandatory`, `advisory` | Enforcement level for this task. | +| `task_result_id` | string | | ID of task result within HCP Terraform. | +| `vcs_branch` | string | | Repository branch that the workspace executes from. This is `null` if the workspace does not have a VCS repository. | +| `vcs_commit_url` | string | | URL to the commit that triggered this run. This is `null` if the workspace does not a VCS repository. | +| `vcs_pull_request_url` | string | | URL to the Pull Request/Merge Request that triggered this run. This is `null` if the run was not triggered. | +| `vcs_repo_url` | string | | URL to the workspace's VCS repository. This is `null` if the workspace does not have a VCS repository. | +| `workspace_app_url` | string | | URL within HCP Terraform to the workspace. | +| `workspace_id` | string | | Id of the workspace the task is associated with. | +| `workspace_name` | string | | Name of the workspace. | +| `workspace_working_directory` | string | | The working directory specified in the run's [workspace settings](/terraform/enterprise/workspaces/settings#terraform-working-directory). | + +#### Post-Plan, Pre-Apply, and Post-Apply Properties + +Requests with `stage` set to `post_plan`, `pre_apply` or `post_apply` contain the following additional properties. + +| Key path | Type | Values | Description | +| ------------------- | ------ | ------ | --------------------------------------------------------- | +| `plan_json_api_url` | string | | The URL to retrieve the JSON Terraform plan for this run. | + +### Sample Payload + +```json +{ + "payload_version": 1, + "stage": "post_plan", + "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q", + "capabilities": { + "outcomes": true + }, + "configuration_version_download_url": "https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download", + "configuration_version_id": "cv-ntv3HbhJqvFzamy7", + "is_speculative": false, + "organization_name": "hashicorp", + "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output", + "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ", + "run_created_at": "2021-09-02T14:47:13.036Z", + "run_created_by": "username", + "run_id": "run-i3Df5to9ELvibKpQ", + "run_message": "Triggered via UI", + "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback", + "task_result_enforcement_level": "mandatory", + "task_result_id": "taskrs-2nH5dncYoXaMVQmJ", + "vcs_branch": "main", + "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22", + "vcs_pull_request_url": null, + "vcs_repo_url": "https://github.com/hashicorp/terraform-random", + "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace", + "workspace_id": "ws-ck4G5bb1Yei5szRh", + "workspace_name": "tfr_github_0", + "workspace_working_directory": "/terraform" +} +``` + +### Request Headers + +The POST request submits the following properties as the request headers. + +| Name | Value | Description | +| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Content-Type` | `application/json` | Specifies the type of data in the request body | +| `User-Agent` | `TFC/1.0 (+https://app.terraform.io; TFC)` | Identifies the request is coming from HCP Terraform | +| `X-TFC-Task-Signature` | string | If the run task is configured with an [HMAC Key](/terraform/enterprise/integrations/run-tasks#securing-your-run-task), this header contains the signed SHA512 sum of the request payload using the configured HMAC key. Otherwise, this is an empty string. | + +## Run Task Callback + +While a run task runs, it may send progressive updates to HCP Terraform with a `running` status. Once an integrator determines that Terraform supports detailed run task outcomes, they can send these outcomes by appending to the run task's callback payload. + +Once the external integration fulfills the request, that integration must call back into HCP Terraform with the overall result of either `passed` or `failed`. Terraform expects this callback within 10 minutes, or the request is considered errored. + +You can send outcomes with a status of `running`, `passed`, or `failed`, but it is a good practice only to send outcomes when a run task is `running`. + +`PATCH :callback_url` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------- | +| `:callback_url` | The `task_result_callback_url` specified in the run task request. Typically `/task-results/:guid/callback`. | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------------------- | +| [200][] | No Content | Successfully submitted a run task result | +| [401][] | [JSON API error object][] | Not authorized to perform action | +| [422][] | [JSON API error object][] | Invalid response payload. This could be caused by invalid attributes, or sending a status that is not accepted. | + +### Request Body + +The PATCH request submits a JSON object with the following properties as a request payload. This payload is also described in the [JSON API schema for run task results](https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-result.json). + +| Key path | Type | Description | +| ----------------------------- | ------ | --------------------------------------------------------------------------------- | +| `data.type` | string | Must be `"task-results"`. | +| `data.attributes.status` | string | The current status of the task. Only `passed`, `failed` or `running` are allowed. | +| `data.attributes.message` | string | (Recommended, but optional) A short message describing the status of the task. | +| `data.attributes.url` | string | (Optional) A URL where users can obtain more information about the task. | +| `relationships.outcomes.data` | array | (Recommended, but optional) A collection of detailed run task outcomes. | + +Status values other than passed, failed, or running return an error. Both the passed and failed statuses represent a final state for a run task. The running status allows one or more partial updates until the task has reached a final state. + +```json +{ + "data": { + "type": "task-results", + "attributes": { + "status": "passed", + "message": "4 passed, 0 skipped, 0 failed", + "url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ" + }, + "relationships": { + "outcomes": { + "data": [...] + } + } + } +} +``` + +#### Outcomes Payload Body + +A run task result may optionally contain one or more detailed outcomes, which improves result visibility and content in the HCP Terraform user interface. The following attributes define the outcome. + +| Key path | Type | Description | +| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `outcome-id` | string | A partner supplied identifier for this outcome. | +| `description` | string | A one-line description of the result. | +| `body` | string | (Optional) A detailed message for the result in Markdown format. It is recommended to keep it under 1MB, with a maximum allowable limit of 5MB. | +| `url` | string | (Optional) A URL that a user can navigate to for more information about this result. | +| `tags` | object | (Optional) An object containing tag arrays, named by the property key. | +| `tags.key` | string | The two or three word name of the header tag. [Special handling](#severity-and-status-tags) is given to `severity` and `status` keys. | +| `tags.key[].label` | string | The text value of the tag. | +| `tags.key[].level` | enum string | (Optional) The error level for the tag. Defaults to `none`, but accepts `none`, `info`, `warning`, or `error`. For levels other than `none`, labels render with a color and icon for that level. | + +##### Severity and Status Tags + +Run task outcomes with tags named "severity" or "status" are enriched within the outcomes display list in HCP Terraform, enabling an earlier response to issues with severity and status. + +```json +{ + "type": "task-result-outcomes", + "attributes": { + "outcome-id": "PRTNR-CC-TF-127", + "description": "ST-2942: S3 Bucket will not enforce MFA login on delete requests", + "tags": { + "Status": [ + { + "label": "Denied", + "level": "error" + } + ], + "Severity": [ + { + "label": "High", + "level": "error" + }, + { + "label": "Recoverable", + "level": "info" + } + ], + "Cost Centre": [ + { + "label": "IT-OPS" + } + ] + }, + "body": "# Resolution for issue ST-2942\n\n## Impact\n\nFollow instructions in the [AWS S3 docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiFactorAuthenticationDelete.html) to manually configure the MFA setting.\n—-- Payload truncated —--", + "url": "https://external.service.dev/result/PRTNR-CC-TF-127" + } +} +``` + +##### Complete Callback Payload Example + +The example below shows a complete payload explaining the data structure of a callback payload, including all the necessary fields. + +```json +{ + "data": { + "type": "task-results", + "attributes": { + "status": "failed", + "message": "0 passed, 0 skipped, 1 failed", + "url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ" + }, + "relationships": { + "outcomes": { + "data": [ + { + "type": "task-result-outcomes", + "attributes": { + "outcome-id": "PRTNR-CC-TF-127", + "description": "ST-2942: S3 Bucket will not enforce MFA login on delete requests", + "tags": { + "Status": [ + { + "label": "Denied", + "level": "error" + } + ], + "Severity": [ + { + "label": "High", + "level": "error" + }, + { + "label": "Recoverable", + "level": "info" + } + ], + "Cost Centre": [ + { + "label": "IT-OPS" + } + ] + }, + "body": "# Resolution for issue ST-2942\n\n## Impact\n\nFollow instructions in the [AWS S3 docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiFactorAuthenticationDelete.html) to manually configure the MFA setting.\n—-- Payload truncated —--", + "url": "https://external.service.dev/result/PRTNR-CC-TF-127" + } + } + ] + } + } + } +} +``` + +### Request Headers + +The PATCH request must use the token supplied in the originating request (`access_token`) for [authentication](/terraform/enterprise/api-docs#authentication). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx new file mode 100644 index 0000000000..a2c11e17c7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx @@ -0,0 +1,814 @@ +--- +page_title: /tasks API reference for Terraform Enterprise +description: >- + Use Terraform Enterprise API's `/tasks` endpoint to read, create, update, and + delete run tasks, and read, update, delete and associate run tasks to + workspaces. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[JSON API Schema document]: https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-results.json + +# Run tasks API reference + +[Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. Run tasks are reusable configurations that you can associate to any workspace in an organization. This page lists the API endpoints for run tasks in an organization and explains how to associate run tasks to workspaces. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +Refer to [run tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) for the API endpoints related triggering run tasks and the expected integration response. + +## Required Permissions + +To interact with run tasks on an organization, you need the [Manage Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#manage-run-tasks). To associate or dissociate run tasks in a workspace, you need the [Manage Workspace Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) on that particular workspace. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a Run Task + +`POST /organizations/:organization_name/tasks` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The organization to create a run task in. The organization must already exist in HCP Terraform, and the token authenticating the API request must have [owner permission](/terraform/enterprise/users-teams-organizations/permissions). | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "tasks"`) | Successfully created a run task | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required unless otherwise specified. + +| Key path | Type | Default | Description | +| -------------------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"tasks"`. | +| `data.attributes.name` | string | | The name of the task. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.url` | string | | URL to send a run task payload. | +| `data.attributes.description` | string | | The description of the run task. Can be up to 300 characters long including spaces, letters, numbers, and special characters. | +| `data.attributes.category` | string | | Must be `"task"`. | +| `data.attributes.hmac-key` | string | | (Optional) HMAC key to verify run task. | +| `data.attributes.enabled` | bool | true | (Optional) Whether the task will be run. | +| `data.attributes.global-configuration.enabled` | bool | false | (Optional) Whether the task will be associated on all workspaces. | +| `data.attributes.global-configuration.stages` | array | | (Optional) An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | +| `data.attributes.global-configuration.enforcement-level` | string | | (Optional) The enforcement level of the workspace task. Must be `"advisory"` or `"mandatory"`. | + +### Sample Payload + +```json +{ + "data": { + "type": "tasks", + "attributes": { + "name": "example", + "url": "http://example.com", + "description": "Simple description", + "hmac_key": "secret", + "enabled": "true", + "category": "task", + "global-configuration": { + "enabled": true, + "stages": ["pre_plan"], + "enforcement-level": "mandatory" + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/tasks +``` + +### Sample Response + +```json +{ + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks", + "attributes": { + "category": "task", + "name": "my-run-task", + "url": "http://example.com", + "description": "Simple description", + "enabled": "true", + "hmac-key": null, + "global-configuration": { + "enabled": true, + "stages": ["pre_plan"], + "enforcement-level": "mandatory" + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [] + } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } + } +} +``` + +## List Run Tasks + +`GET /organizations/:organization_name/tasks` + +| Parameter | Description | +| -------------------- | ----------------------------------- | +| `:organization_name` | The organization to list tasks for. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | Request was successful | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `include` | **Optional.** Allows including related resource data. Value must be a comma-separated list containing one or more of `workspace_tasks` or `workspace_tasks.workspace`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 run tasks per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/tasks +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks", + "attributes": { + "category": "task", + "name": "my-task", + "url": "http://example.com", + "description": "Simple description", + "enabled": "true", + "hmac-key": null, + "global-configuration": { + "enabled": true, + "stages": ["pre_plan"], + "enforcement-level": "mandatory" + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [] + } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a Run Task + +`GET /tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------- | +| `:id` | The ID of the task to show. Use the ["List Run Tasks"](#list-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Run task not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `include` | **Optional.** Allows including related resource data. Value must be a comma-separated list containing one or more of `workspace_tasks` or `workspace_tasks.workspace`. | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV +``` + +### Sample Response + +```json +{ + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks", + "attributes": { + "category": "task", + "name": "my-task", + "url": "http://example.com", + "description": "Simple description", + "enabled": "true", + "hmac-key": null, + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [ + { + "id": "task-xjKZw9KaeXda61az", + "type": "tasks" + } + ] + } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } + } +} +``` + +## Update a Run Task + +`PATCH /tasks/:id` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------- | +| `:id` | The ID of the task to update. Use the ["List Run Tasks"](#list-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Run task not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required unless otherwise specified. + +| Key path | Type | Default | Description | +| -------------------------------------------------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"tasks"`. | +| `data.attributes.name` | string | (previous value) | The name of the run task. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.url` | string | (previous value) | URL to send a run task payload. | +| `data.attributes.description` | string | | The description of the run task. Can be up to 300 characters long including spaces, letters, numbers, and special characters. | +| `data.attributes.category` | string | (previous value) | Must be `"task"`. | +| `data.attributes.hmac-key` | string | (previous value) | (Optional) HMAC key to verify run task. | +| `data.attributes.enabled` | bool | (previous value) | (Optional) Whether the task will be run. | +| `data.attributes.global-configuration.enabled` | bool | (previous value) | (Optional) Whether the task will be associated on all workspaces. | +| `data.attributes.global-configuration.stages` | array | (previous value) | (Optional) An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | +| `data.attributes.global-configuration.enforcement-level` | string | (previous value) | (Optional) The enforcement level of the workspace task. Must be `"advisory"` or `"mandatory"`. | + +### Sample Payload + +```json +{ + "data": { + "type": "tasks", + "attributes": { + "name": "new-example", + "url": "http://new-example.com", + "description": "New description", + "hmac_key": "new-secret", + "enabled": "false", + "category": "task", + "global-configuration": { + "enabled": false + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV +``` + +### Sample Response + +```json +{ + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks", + "attributes": { + "category": "task", + "name": "new-example", + "url": "http://new-example.com", + "description": "New description", + "enabled": "false", + "hmac-key": null, + "global-configuration": { + "enabled": false, + "stages": ["pre_plan"], + "enforcement-level": "mandatory" + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [ + { + "id": "wstask-xjKZw9KaeXda61az", + "type": "workspace-tasks" + } + ] + } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } + } +} +``` + +## Delete a Run Task + +`DELETE /tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the run task to delete. Use the ["List Run Tasks"](#list-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the run task | +| [404][] | [JSON API error object][] | Run task not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV +``` + +## Associate a Run Task to a Workspace + +`POST /workspaces/:workspace_id/tasks` + +| Parameter | Description | +| --------------- | ------------------------ | +| `:workspace_id` | The ID of the workspace. | + +This endpoint associates an existing run task to a specific workspace. + +This involves setting the run task enforcement level, which determines whether the run task blocks runs from completing. + +- Advisory run tasks can not block a run from completing. If the task fails, the run will proceed with a warning. + +- Mandatory run tasks block a run from completing. If the task fails (including a timeout or unexpected remote error condition), the run stops with an error. + +You may also configure the run task to begin during specific [run stages](/terraform/enterprise/run/states). Run tasks use the [Post-Plan Stage](/terraform/enterprise/run/states#the-post-plan-stage) by default. + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Workspace or run task not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"workspace-tasks"`. | +| `data.attributes.enforcement-level` | string | | The enforcement level of the workspace task. Must be `"advisory"` or `"mandatory"`. | +| `data.attributes.stage` | string | `"post_plan"` | **DEPRECATED** Use `stages` instead. The stage in the run lifecycle when the run task should begin. Must be `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | +| `data.attributes.stages` | array | `["post_plan"]` | An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | +| `data.relationships.task.data.id` | string | | The ID of the run task. | +| `data.relationships.task.data.type` | string | | Must be `"tasks"`. | + +### Sample Payload + +```json +{ + "data": { + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-PphL7ix3yGasYGrq/tasks +``` + +### Sample Response + +```json +{ + "data": { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-PphL7ix3yGasYGrq", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-PphL7ix3yGasYGrq/tasks/task-tBXYu8GVAFBpcmPm" + } + } +} +``` + +## List Workspace Run Tasks + +`GET /workspaces/:workspace_id/tasks` + +| Parameter | Description | +| --------------- | -------------------------------- | +| `:workspace_id` | The workspace to list tasks for. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | Request was successful | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 run tasks per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-hu74ST39g566Q4m5", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-kRsDRPtTmtcEme4t", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/task-tBXYu8GVAFBpcmPm" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show Workspace Run Task + +`GET /workspaces/:workspace_id/tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the workspace task to show. Use the ["List Workspace Run Tasks"](#list-workspace-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace run task not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm +``` + +### Sample Response + +```json +{ + "data": { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-hu74ST39g566Q4m5", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-kRsDRPtTmtcEme4t", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm" + } + } +} +``` + +## Update Workspace Run Task + +`PATCH /workspaces/:workspace_id/tasks/:id` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the task to update. Use the ["List Workspace Run Tasks"](#list-workspace-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace run task not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | (previous value) | Must be `"workspace-tasks"`. | +| `data.attributes.enforcement-level` | string | (previous value) | The enforcement level of the workspace run task. Must be `"advisory"` or `"mandatory"`. | +| `data.attributes.stage` | string | (previous value) | **DEPRECATED** Use `stages` instead. The stage in the run lifecycle when the run task should begin. Must be `"pre_plan"` or `"post_plan"`. | +| `data.attributes.stages` | array | (previous value) | An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | + +### Sample Payload + +```json +{ + "data": { + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "mandatory", + "stages": ["post_plan"] + } + } +} +``` + +#### Deprecated Payload + +```json +{ + "data": { + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "mandatory", + "stages": ["post_plan"] + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm +``` + +### Sample Response + +```json +{ + "data": { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "mandatory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-hu74ST39g566Q4m5", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-kRsDRPtTmtcEme4t", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/task-tBXYu8GVAFBpcmPm" + } + } +} +``` + +## Delete Workspace Run Task + +`DELETE /workspaces/:workspace_id/tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the Workspace run task to delete. Use the ["List Workspace Run Tasks"](#list-workspace-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the workspace run task | +| [404][] | [JSON API error object][] | Workspace run task not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-triggers.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-triggers.mdx new file mode 100644 index 0000000000..e557a25a36 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run-triggers.mdx @@ -0,0 +1,349 @@ +--- +page_title: /run-triggers API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/run-triggers` endpoint to read, create, + and delete run triggers. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Run triggers API reference + +## Create a Run Trigger + +`POST /workspaces/:workspace_id/run-triggers` + +| Parameter | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to create the run trigger in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------------------ | +| [201][] | [JSON API document][] (`type: "run-triggers"`) | Successfully created a run trigger | +| [404][] | [JSON API error object][] | Workspace or sourceable not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Permissions + +In order to create a run trigger, the user must have admin access to the specified workspace and permission to read runs for the sourceable workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.relationships.sourceable.data` | object | | A JSON API relationship object that represents the source workspace for the run trigger. This object must have `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Sample Payload + +```json +{ + "data": { + "relationships": { + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --request POST \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/run-triggers +``` + +### Sample Response + +```json +{ + "data": { + "id": "rt-3yVQZvHzf5j3WRJ1", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-2", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## List Run Triggers + +`GET /workspaces/:workspace_id/run-triggers` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list run triggers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "run-triggers"`) | Request was successful | +| [400][] | [JSON API error object][] | Required parameter `filter[run-trigger][type]` is missing or has been given an invalid value | +| [404][] | [JSON API error object][] | Workspace not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[run-trigger][type]` | **Required** Which type of run triggers to list; valid values are `inbound` or `outbound`. `inbound` run triggers create runs in the specified workspace, and `outbound` run triggers create runs in other workspaces. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 run triggers per page. | + +### Permissions + +In order to list run triggers, the user must have permission to read runs for the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "rt-WygcwSBuYaQWrM39", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-2", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-WygcwSBuYaQWrM39" + } + }, + { + "id": "rt-8F5JFydVYAmtTjET", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-3", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-BUHBEM97xboT8TVz", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-8F5JFydVYAmtTjET" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show a Run Trigger + +`GET /run-triggers/:run_trigger_id` + +| Parameter | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:run_trigger_id` | The ID of the run trigger to show. Send a `GET` request to the `run-triggers` endpoint to find IDs. Refer to [List Run Triggers](#list-run-triggers) for details. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "run-triggers"`) | The request was successful | +| [404][] | [JSON API error object][] | Run trigger not found or user unauthorized to perform action | + +### Permissions + +In order to show a run trigger, the user must have permission to read runs for either the workspace or sourceable workspace of the specified run trigger. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1 +``` + +### Sample Response + +```json +{ + "data": { + "id": "rt-3yVQZvHzf5j3WRJ1", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-2", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## Delete a Run Trigger + +`DELETE /run-triggers/:run_trigger_id` + +| Parameter | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:run_trigger_id` | The ID of the run trigger to delete. Send a `GET` request to the `run-triggers` endpoint o find IDs. Refer to [List Run Triggers](#list-run-triggers) for details. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | No Content | Successfully deleted the run trigger | +| [404][] | [JSON API error object][] | Run trigger not found or user unauthorized to perform action | + +### Permissions + +In order to delete a run trigger, the user must have admin access to the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1 +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +These includes respect read permissions. If you do not have access to read the related resource, it will not be returned. + +- `workspace` - The full workspace object. +- `sourceable` - The full source workspace object. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run.mdx new file mode 100644 index 0000000000..950e1d8880 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/run.mdx @@ -0,0 +1,902 @@ +--- +page_title: /runs API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/runs` endpoint to read, get, create, + apply, discard, execute, and cancel Terraform runs. You can also list a + workspace's or organization's runs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Runs API reference + +-> **Note:** Before working with the runs or configuration versions APIs, read the [API-driven run workflow](/terraform/enterprise/run/api) page, which includes both a full overview of this workflow and a walkthrough of a simple implementation of it. + +Performing a run on a new configuration is a multi-step process. + +1. [Create a configuration version on the workspace](/terraform/enterprise/api-docs/configuration-versions#create-a-configuration-version). +2. [Upload configuration files to the configuration version](/terraform/enterprise/api-docs/configuration-versions#upload-configuration-files). +3. [Create a run on the workspace](#create-a-run); this is done automatically when a configuration file is uploaded. +4. [Create and queue an apply on the run](#apply-a-run); if the run can't be auto-applied. + +Alternatively, you can create a run with a pre-existing configuration version, even one from another workspace. This is useful for promoting known good code from one workspace to another. + +## Attributes + +### Run States + +The run state is found in `data.attributes.status`, and you can reference the following list of possible states. + +| State | Description | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `pending` | The initial status of a run after creation. | +| `fetching` | The run is waiting for HCP Terraform to fetch the configuration from VCS. | +| `fetching_completed` | HCP Terraform has fetched the configuration from VCS and the run will continue. | +| `pre_plan_running` | The pre-plan phase of the run is in progress. | +| `pre_plan_completed` | The pre-plan phase of the run has completed. | +| `queuing` | HCP Terraform is queuing the run to start the planning phase. | +| `plan_queued` | HCP Terraform is waiting for its backend services to start the plan. | +| `planning` | The planning phase of a run is in progress. | +| `planned` | The planning phase of a run has completed. | +| `cost_estimating` | The cost estimation phase of a run is in progress. | +| `cost_estimated` | The cost estimation phase of a run has completed. | +| `policy_checking` | The sentinel policy checking phase of a run is in progress. | +| `policy_override` | A sentinel policy has soft failed, and a user can override it to continue the run. | +| `policy_soft_failed` | A sentinel policy has soft failed for a plan-only run. This is a final state. | +| `policy_checked` | The sentinel policy checking phase of a run has completed. | +| `confirmed` | A user has confirmed the plan. | +| `post_plan_running` | The post-plan phase of the run is in progress. | +| `post_plan_completed` | The post-plan phase of the run has completed. | +| `planned_and_finished` | The run is completed. This status only exists for plan-only runs and runs that produce a plan with no changes to apply. This is a final state. | +| `planned_and_saved` | The run has finished its planning, checks, and estimates, and can be confirmed for apply. This status is only used for saved plan runs. | +| `apply_queued` | Once the changes in the plan have been confirmed, the run will transition to `apply_queued`. This status indicates that the run should start as soon as the backend services that run terraform have available capacity. In HCP Terraform, you should seldom see this status, as our aim is to always have capacity. However, in Terraform Enterprise this status will be more common due to the self-hosted nature. | +| `applying` | Terraform is applying the changes specified in the plan. | +| `applied` | Terraform has applied the changes specified in the plan. | +| `discarded` | The run has been discarded. This is a final state. | +| `errored` | The run has errored. This is a final state. | +| `canceled` | The run has been canceled. | +| `force_canceled` | A workspace admin forcefully canceled the run. | + +### Run Operations + +The run operation specifies the Terraform execution mode. You can reference the following list of possible execution modes and use them as query parameters in the [workspace](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace) and [organization](/terraform/enterprise/api-docs/run#list-runs-in-a-organization) runs lists. + +| Operation | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plan_only` | The run does not have an apply phase. This is also called a [_speculative plan_](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan). | +| `plan_and_apply` | The run includes both plan and apply phases. | +| `save_plan` | The run is a saved plan run. It can include both plan and apply phases, but only becomes the workspace's current run if a user chooses to apply it. | +| `refresh_only` | The run should update Terraform state, but not make changes to resources. | +| `destroy` | The run should destroy all objects, regardless of configuration changes. | +| `empty_apply` | The run should perform an apply with no changes to resources. This is most commonly used to [upgrade terraform state versions](/terraform/enterprise/workspaces/state#upgrading-state). | + +### Run Sources + +You can use the following sources as query parameters in [workspace](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace) and [organization](/terraform/enterprise/api-docs/run#list-runs-in-a-organization) runs lists. + +| Source | Description | +| --------------------------- | --------------------------------------------------------------------------------------- | +| `tfe-ui` | Indicates a run was queued from HCP Terraform UI. | +| `tfe-api` | Indicates a run was queued from HCP Terraform API. | +| `tfe-configuration-version` | Indicates a run was queued from a Configuration Version, triggered from a VCS provider. | + +### Run Status Groups + +The run status group specifies a collection of run states by logical category. + +| Group | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `non_final` | Inclusive of runs that are currently running, require user confirmation, or are queued/pending. | +| `final` | Inclusive of runs that have reached their final and terminal state. | +| `discardable` | Inclusive of runs whose state falls under the following: `planned`, `planned_and_saved`, `cost_estimated`, `policy_checked`, `policy_override`, `post_plan_running`, `post_plan_completed` | + +## Create a Run + +`POST /runs` + +A run performs a plan and apply, using a configuration version and the workspace’s current variables. You can specify a configuration version when creating a run; if you don’t provide one, the run defaults to the workspace’s most recently used version. (A configuration version is “used” when it is created or used for a run in this workspace.) + +Creating a run requires permission to queue plans for the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +When creating a run, you may optionally provide a list of variable objects containing key and value attributes. These values apply to that run specifically and take precedence over variables with the same key applied to the workspace(e.g., variable sets). Refer to [Variable Precedence](/terraform/enterprise/workspaces/variables#precedence) for more information. All values must be expressed as an HCL literal in the same syntax you would use when writing Terraform code. Refer to [Types](/terraform/language/expressions/types#types) in the Terraform documentation for more details. + +Setting `debugging_mode: true` enables debugging mode for the queued run only. This is equivalent to setting the `TF_LOG` environment variable to `TRACE` for this run. See [Debugging Terraform](/terraform/internals/debugging) for more information. + +**Sample Run Variables:** + +```json +"attributes": { + "variables": [ + { "key": "replicas", "value": "2" }, + { "key": "access_key", "value": "\"ABCDE12345\"" } + ] +} +``` + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.allow-empty-apply` | bool | none | Specifies whether Terraform can apply the run even when the plan [contains no changes](/terraform/enterprise/run/modes-and-options#allow-empty-apply). Use this property to [upgrade state](/terraform/enterprise/workspaces/state#upgrading-state) after upgrading a workspace to a new terraform version. | +| `data.attributes.allow-config-generation` | bool | `false` | Specifies whether Terraform can [generate resource configuration](/terraform/language/import/generating-configuration) when planning to import new resources. When set to `false`, Terraform returns an error when `import` blocks do not have a corresponding `resource` block. | +| `data.attributes.auto-apply` | bool | Defaults to the [Auto Apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) workspace setting. | Determines if Terraform automatically applies the configuration on a successful `terraform plan`. | +| `data.attributes.debugging-mode` | bool | `false` | When set to `true`, enables verbose logging for the queued plan. | +| `data.attributes.is-destroy` | bool | `false` | When set to `true`, the plan destroys all provisioned resources. Mutually exclusive with `refresh-only`. | +| `data.attributes.message` | string | `"Queued manually via the Terraform Enterprise API"` | Specifies the message associated with this run. | +| `data.attributes.refresh` | bool | `true` | Specifies whether or not to refresh the state before a plan. | +| `data.attributes.refresh-only` | bool | `false` | When set to `true`, this run refreshes the state without modifying any resources. Mutually exclusive with `is-destroy`. | +| `data.attributes.replace-addrs` | array\[string] | | Specifies an optional list of resource addresses to be passed to the `-replace` flag. | +| `data.attributes.target-addrs` | array\[string] | | Specifies an optional list of resource addresses to be passed to the `-target` flag. | +| `data.attributes.variables` | array\[{key, value}] | (empty array) | Specifies an optional list of run-specific variable values. Refer to [Run-Specific Variables](/terraform/enterprise/workspaces/variables/managing-variables#run-specific-variables) for details. | +| `data.attributes.plan-only` | bool | (from configuration version) | Specifies if this is a [speculative, plan-only](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) run that Terraform cannot apply. Often used in conjunction with terraform-version in order to test whether an upgrade would succeed. | +| `data.attributes.save-plan` | bool | `false` | When set to `true`, the run is executed as a `save plan` run. A `save plan` run plans and checks the configuration without becoming the workspace's current run. These run types only becomes the current run if you confirm that you want to apply them when prompted. When creating new [configuration versions](/terraform/enterprise/api-docs/configuration-versions) for saved plan runs, be sure to make them `provisional`. | +| `data.attributes.terraform-version` | string | none | Specifies the Terraform version to use in this run. Only valid for plan-only runs; must be a valid Terraform version available to the organization. | +| `data.relationships.workspace.data.id` | string | none | Specifies the workspace ID to execute the run in. | +| `data.relationships.configuration-version.data.id` | string | none | Specifies the configuration version to use for this run. If the `configuration-version` object is omitted, Terraform uses the workspace's latest configuration version to create the run . | + +| Status | Response | Reason | +| ------- | -------------------------------------- | --------------------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "runs"`) | Successfully created a run | +| [404][] | [JSON API error object][] | Organization or workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "message": "Custom message" + }, + "type":"runs", + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-LLGHCr4SWy28wyGN" + } + }, + "configuration-version": { + "data": { + "type": "configuration-versions", + "id": "cv-n4XQPBa2QnecZJ4G" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/runs +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-CZcmD7eagjhyX0vN" + } + } +} +``` + +## Apply a Run + +`POST /runs/:run_id/actions/apply` + +| Parameter | Description | +| --------- | ------------------- | +| `run_id` | The run ID to apply | + +Applies a run that is paused waiting for confirmation after a plan. This includes runs in the "needs confirmation" and "policy checked" states. This action is only required for runs that can't be auto-applied. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs for the workspace. + +-> **Note:** If the run has a soft failed sentinel policy, you will need to [override the policy check](/terraform/enterprise/api-docs/policy-checks#override-policy) before Terraform can apply the run. You can find policy check details in the `relationships` section of the [run details endpoint](#get-run-details) response. + +Applying a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint queues the request to perform an apply; the apply might not happen immediately. + +Since this endpoint represents an action (not a resource), it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------- | +| [202][] | none | Successfully queued an apply request. | +| [409][] | [JSON API error object][] | Run was not paused for confirmation; apply not allowed. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ---------------------------------- | +| `comment` | string | `null` | An optional comment about the run. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment":"Looks good to me" +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/apply +``` + +## List Runs in a Workspace + +`GET /workspaces/:workspace_id/runs` + +| Parameter | Description | +| -------------- | ---------------------------------- | +| `workspace_id` | The workspace ID to list runs for. | + +By default, `plan_only` runs will be excluded from the results. To see all runs, use `filter[operation]` with all available operations included as a comma-separated list. +This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second. + +| Status | Response | Reason | +| ------- | ------------------------------------------------ | ------------------------ | +| [200][] | Array of [JSON API document][]s (`type: "runs"`) | Successfully listed runs | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | Required | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `page[number]` | If omitted, the endpoint returns the first page. | Optional | +| `page[size]` | If omitted, the endpoint returns 20 runs per page. | Optional | +| `filter[operation]` | A comma-separated list of run operations. The result lists runs that perform one of these operations. For details on options, refer to [Run operations](/terraform/enterprise/api-docs/run#run-operations). | Optional | +| `filter[status]` | A comma-separated list of run statuses. The result lists runs that are in one of the statuses you specify. For details on options, refer to [Run states](/terraform/enterprise/api-docs/run#run-states). | Optional | +| `filter[agent_pool_names]` | A comma-separated list of agent pool names. The result lists runs that use one of the agent pools you specify. | Optional | +| `filter[source]` | A comma-separated list of run sources. The result lists runs that came from one of the sources you specify. Options are listed in [Run Sources](/terraform/enterprise/api-docs/run#run-sources). | Optional | +| `filter[status_group]` | A single status group. The result lists runs whose status falls under this status group. For details on options, refer to [Run status groups](/terraform/enterprise/api-docs/run#run-status-groups). | Optional | +| `filter[timeframe]` | A single year period. The result lists runs that were created within the year you specify. An integer year or the string "year" for the past year are valid values. If omitted, the endpoint returns all runs since the creation of the workspace. | Optional | +| `search[user]` | Searches for runs that match the VCS username you supply. | Optional | +| `search[commit]` | Searches for runs that match the commit sha you specify. | Optional | +| `search[basic]` | Searches for runs that match the VCS username, commit sha, run_id, or run message your specify. HCP Terraform prioritizes `search[commit]` or `search[user]` and ignores `search[basic]` in favor of the higher priority parameters if you include them in your query. | Optional | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7" + } + }, + {...} + ], + "links": { + "first": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=1&page[size]=20", + "last": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=19206&page[size]=20", + "self": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=2&page[size]=20", + "prev": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=1&page[size]=20", + "next": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=3&page[size]=20" + }, + "meta": { + "pagination": { + "current-page": 2, + "next-page": 3, + "prev-page": 1, + "page-size": 20, + "total-count": 384105, + "total-pages": 19206 + } + } +} +``` + +## List Runs in an Organization + +`GET /organizations/:organization_name/runs` + +| Parameter | Description | +| ------------------- | --------------------------------------- | +| `organization_name` | The organization name to list runs for. | + +This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second. + +Note that this endpoint differs from others in the pagination metadata included in the response, such as the exclusion of the typical `total-count` and `total-pages`. See the Sample Response below for more details. + +| Status | Response | Reason | +| ------- | ------------------------------------------------ | ------------------------ | +| [200][] | Array of [JSON API document][]s (`type: "runs"`) | Successfully listed runs | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | Required | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `page[number]` | If omitted, the endpoint returns the first page. | Optional | +| `page[size]` | If omitted, the endpoint returns 20 runs per page. | Optional | +| `filter[operation]` | A comma-separated list of run operations. The result lists runs that perform one of these operations. For details on options, refer to [Run operations](/terraform/enterprise/api-docs/run#run-operations). | Optional | +| `filter[status]` | A comma-separated list of run statuses. The result lists runs that are in one of the statuses you specify. For details on options, refer to [Run states](/terraform/enterprise/api-docs/run#run-states). | Optional | +| `filter[agent_pool_names]` | A comma-separated list of agent pool names. The result lists runs that use one of the agent pools you specify. | Optional | +| `filter[workspace_names]` | A comma-separated list of workspace names. The result lists runs that belong to one of the workspaces your specify. | Optional | +| `filter[source]` | A comma-separated list of run sources. The result lists runs that came from one of the sources you specify. Options are listed in [Run Sources](/terraform/enterprise/api-docs/run#run-sources). | Optional | +| `filter[status_group]` | A single status group. The result lists runs whose status falls under this status group. For details on options, refer to [Run status groups](/terraform/enterprise/api-docs/run#run-status-groups). | Optional | +| `filter[timeframe]` | A single year period. The result lists runs that were created within the year you specify. An integer year or the string "year" for the past year are valid values. If omitted, the endpoint returns runs created in the last year. | Optional | +| `search[user]` | Searches for runs that match the VCS username you supply. | Optional | +| `search[commit]` | Searches for runs that match the commit sha you specify. | Optional | +| `search[basic]` | Searches for runs that match the VCS username, commit sha, run_id, or run message your specify. HCP Terraform prioritizes `search[commit]` or `search[user]` and ignores `search[basic]` in favor of the higher priority parameters if you include them in your query. | Optional | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/runs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7" + } + }, + {...} + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=2&page[size]=20", + "prev": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=1&page[size]=20", + "next": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=3&page[size]=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "next-page": 2, + "prev-page": null, + "page-size": 20 + } + } +} +``` + +## Get run details + +`GET /runs/:run_id` + +| Parameter | Description | +| --------- | ------------------ | +| `:run_id` | The run ID to get. | + +This endpoint is used for showing details of a specific run. + +| Status | Response | Reason | +| ------- | -------------------------------------- | ------------------------------------ | +| [200][] | [JSON API document][] (`type: "runs"`) | Success | +| [404][] | [JSON API error object][] | Run not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/runs/run-bWSq4YeYpfrW4mx7 +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "task-stages": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7" + } + } +} +``` + +## Discard a Run + +`POST /runs/:run_id/actions/discard` + +| Parameter | Description | +| --------- | --------------------- | +| `run_id` | The run ID to discard | + +The `discard` action can be used to skip any remaining work on runs that are paused waiting for confirmation or priority. This includes runs in the "pending," "needs confirmation," "policy checked," and "policy override" states. + +Discarding a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint queues the request to perform a discard; the discard might not happen immediately. After discarding, the run is completed and later runs can proceed. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [202][] | none | Successfully queued a discard request. | +| [409][] | [JSON API error object][] | Run was not paused for confirmation or priority; discard not allowed. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ------------------------------------------------------ | +| `comment` | string | `null` | An optional explanation for why the run was discarded. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment": "This run was discarded" +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/discard +``` + +## Cancel a Run + +`POST /runs/:run_id/actions/cancel` + +| Parameter | Description | +| --------- | -------------------- | +| `run_id` | The run ID to cancel | + +The `cancel` action can be used to interrupt a run that is currently planning or applying. Performing a cancel is roughly equivalent to hitting ctrl+c during a Terraform plan or apply on the CLI. The running Terraform process is sent an `INT` signal, which instructs Terraform to end its work and wrap up in the safest way possible. + +Canceling a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint queues the request to perform a cancel; the cancel might not happen immediately. After canceling, the run is completed and later runs can proceed. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------- | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Run was not planning or applying; cancel not allowed. | +| [404][] | [JSON API error object][] | Run was not found or user not authorized. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ----------------------------------------------------- | +| `comment` | string | `null` | An optional explanation for why the run was canceled. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment": "This run was stuck and would never finish." +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/cancel +``` + +## Forcefully cancel a run + +`POST /runs/:run_id/actions/force-cancel` + +| Parameter | Description | +| --------- | -------------------- | +| `run_id` | The run ID to cancel | + +The `force-cancel` action is like [cancel](#cancel-a-run), but ends the run immediately. Once invoked, the run is placed into a `canceled` state, and the running Terraform process is terminated. The workspace is immediately unlocked, allowing further runs to be queued. The `force-cancel` operation requires admin access to the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint enforces a prerequisite that a [non-forceful cancel](#cancel-a-run) is performed first, and a cool-off period has elapsed. To determine if this criteria is met, it is useful to check the `data.attributes.is-force-cancelable` value of the [run details endpoint](#get-run-details). The time at which the force-cancel action will become available can be found using the [run details endpoint](#get-run-details), in the key `data.attributes.force_cancel_available_at`. Note that this key is only present in the payload after the initial cancel has been initiated. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +~> **Warning:** This endpoint has potentially dangerous side-effects, including loss of any in-flight state in the running Terraform process. Use this operation with extreme caution. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Run was not planning or applying, has not been canceled non-forcefully, or the cool-off period has not yet passed. | +| [404][] | [JSON API error object][] | Run was not found or user not authorized. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ----------------------------------------------------- | +| `comment` | string | `null` | An optional explanation for why the run was canceled. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment": "This run was stuck and would never finish." +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/force-cancel +``` + +## Forcefully execute a run + +`POST /runs/:run_id/actions/force-execute` + +| Parameter | Description | +| --------- | --------------------- | +| `run_id` | The run ID to execute | + +The force-execute action cancels all prior runs that are not already complete, unlocking the run's workspace and allowing the run to be executed. (It initiates the same actions as the "Run this plan now" button at the top of the view of a pending run.) + +Force-executing a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint enforces the following prerequisites: + +- The target run is in the "pending" state. +- The workspace is locked by another run. +- The run locking the workspace can be discarded. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +~> **Note:** While useful at times, force-executing a run circumvents the typical workflow of applying runs using HCP Terraform. It is not intended for regular use. If you find yourself using it frequently, please reach out to HashiCorp Support for help in developing an alternative approach. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------- | +| [202][] | none | Successfully initiated the force-execution process. | +| [403][] | [JSON API error object][] | Run is not pending, its workspace was not locked, or its workspace association was not found. | +| [409][] | [JSON API error object][] | The run locking the workspace was not in a discardable state. | +| [404][] | [JSON API error object][] | Run was not found or user not authorized. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/force-execute +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `plan` - Additional information about plans. +- `apply` - Additional information about applies. +- `created_by` - Full user records of the users responsible for creating the runs. +- `cost_estimate` - Additional information about cost estimates. +- `configuration_version` - The configuration record used in the run. +- `configuration_version.ingress_attributes` - The commit information used in the run. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/ssh-keys.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/ssh-keys.mdx new file mode 100644 index 0000000000..70f2e54828 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/ssh-keys.mdx @@ -0,0 +1,320 @@ +--- +page_title: /ssh-keys API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/ssh-keys` endpoint to read, get, create, + update, and delete an organization's SSH keys. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# SSH keys API reference + +The `ssh-key` object represents an SSH key which includes a name and the SSH private key. An organization can have multiple SSH keys available. + +SSH keys can be used in two places: + +- You can assign them to VCS provider integrations, which are available in the API as `oauth-tokens`. Refer to [OAuth Tokens](/terraform/enterprise/api-docs/oauth-tokens) for additional information. Azure DevOps Server and Bitbucket Data Center require an SSH key. Other providers only require an SSH key when your repositories include submodules that are only accessible using an SSH connection instead of your VCS provider's API. +- They can be [assigned to workspaces](/terraform/enterprise/api-docs/workspaces#assign-an-ssh-key-to-a-workspace) and used when Terraform needs to clone modules from a Git server. This is only necessary when your configurations directly reference modules from a Git server; you do not need to do this if you use HCP Terraform's [private module registry](/terraform/enterprise/registry). + +Listing and viewing SSH keys requires either permission to manage VCS settings for the organization, or admin access to at least one workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +~> **Important:** The list and read methods on this API only provide metadata about SSH keys. The actual private key text is write-only, and HCP Terraform never provides it to users via the API or UI. + +## List SSH Keys + +`GET /organizations/:organization_name/ssh-keys` + +| Parameter | Description | +| -------------------- | -------------------------------------------------- | +| `:organization_name` | The name of the organization to list SSH keys for. | + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------- | +| [200][] | Array of [JSON API document][]s (`type: "ssh-keys"`) | Success | +| [404][] | [JSON API error object][] | Organization not found or user not authorized | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------ | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 ssh keys per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/ssh-keys +``` + +### Sample Response + +```json +{ + "data": [ + { + "attributes": { + "name": "SSH Key" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } + ] +} +``` + +## Get an SSH Key + +`GET /ssh-keys/:ssh_key_id` + +| Parameter | Description | +| ------------- | ---------------------- | +| `:ssh_key_id` | The SSH key ID to get. | + +This endpoint is for looking up the name associated with an SSH key ID. It does not retrieve the key text. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ---------------------------------------- | +| [200][] | [JSON API document][] (`type: "ssh-keys"`) | Success | +| [404][] | [JSON API error object][] | SSH key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM +``` + +### Sample Response + +```json +{ + "data": { + "attributes": { + "name": "SSH Key" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } +} +``` + +## Create an SSH Key + +`POST /organizations/:organization_name/ssh-keys` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create an SSH key in. The organization must already exist, and the token authenticating the API request must have permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "ssh-keys"`) | Success | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------- | ------ | ------- | -------------------------------- | +| `data.type` | string | | Must be `"ssh-keys"`. | +| `data.attributes.name` | string | | A name to identify the SSH key. | +| `data.attributes.value` | string | | The text of the SSH private key. | + +### Sample Payload + +```json +{ + "data": { + "type": "ssh-keys", + "attributes": { + "name": "SSH Key", + "value": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAm6+JVgl..." + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/ssh-keys +``` + +### Sample Response + +```json +{ + "data": { + "attributes": { + "name": "SSH Key" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } +} +``` + +## Update an SSH Key + +`PATCH /ssh-keys/:ssh_key_id` + +| Parameter | Description | +| ------------- | ------------------------- | +| `:ssh_key_id` | The SSH key ID to update. | + +This endpoint replaces the name of an existing SSH key. + +Editing SSH keys requires permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ---------------------------------------- | +| [200][] | [JSON API document][] (`type: "ssh-keys"`) | Success | +| [404][] | [JSON API error object][] | SSH key not found or user not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------- | ------ | --------- | --------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"ssh-keys"`. | +| `data.attributes.name` | string | (nothing) | A name to identify the SSH key. If omitted, the existing name is preserved. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "SSH Key for GitHub" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM +``` + +### Sample Response + +```json +{ + "data": { + "attributes": { + "name": "SSH Key for GitHub" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } +} +``` + +## Delete an SSH Key + +`DELETE /ssh-keys/:ssh_key_id` + +| Parameter | Description | +| ------------- | ------------------------- | +| `:ssh_key_id` | The SSH key ID to delete. | + +Deleting SSH keys requires permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------- | +| [204][] | No Content | Success | +| [404][] | [JSON API error object][] | SSH key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/stability-policy.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/stability-policy.mdx new file mode 100644 index 0000000000..1b59e2d1f2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/stability-policy.mdx @@ -0,0 +1,25 @@ +--- +page_title: API stability policy for Terraform Enterprise +description: >- + Learn how HashiCorp plans for stability, backward compatibility, and + deprecation for the Terraform Enterprise APIs. +source: terraform-docs-common +--- + +# API stability policy + +The HCP Terraform API will continue to evolve, but we consider it stable for general use, and HashiCorp will maintain all stable API endpoints in a backwards compatible manner. (Stable endpoints are any endpoints _not_ marked as beta.) If we need to make a change that we consider backwards incompatible, then we will create a new endpoint that serves the same purpose; the old endpoint will be maintained until declared [deprecated](#deprecation-policy). + +The following changes are considered to be backwards compatible: + +- Adding new API endpoints. +- Adding new attributes, links, or relationships to existing API requests and responses. +- Adding new optional query parameters to existing API requests. + +Security vulnerabilities are an exception to this stability policy; we will make backwards incompatible changes to stable endpoints if it is necessary to protect our security or the security of our users. + +Endpoints that are in beta are subject to change without notice. + +## Deprecation Policy + +The deprecation policy provides users the opportunity to continue to consume API endpoints for a period of time after they have been superseded. Deprecation notices for endpoints should be readily available through various channels of communication, including documentation and HTTP responses. An endpoint should be available for at least three (3) months from the date on which it has been declared deprecated. (This time is cited as a minimum; endpoint availability may be longer based on contracted agreements.) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/state-version-outputs.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/state-version-outputs.mdx new file mode 100644 index 0000000000..cb5ef168b0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/state-version-outputs.mdx @@ -0,0 +1,244 @@ +--- +page_title: /state-version-outputs API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/state-version-outputs` endpoint to read + the outputs from a specified Terraform state version or a workspace's current + outputs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# State version outputs API reference + +State version outputs are the [output values](/terraform/language/values/outputs) from a Terraform state file. They include +the name and value of the output, as well as a sensitive boolean if the value should be hidden by default in UIs. + +~> **Important:** The state version outputs for a state version (as well as some other information about it) might be **populated asynchronously** by HCP Terraform. These values might not be immediately available after the state version is uploaded. The `resources-processed` property on the associated [state version object](/terraform/enterprise/api-docs/state-versions) indicates whether or not HCP Terraform has finished any necessary asynchronous processing. If you need to use these values, be sure to wait for `resources-processed` to become `true` before assuming that the values are in fact empty. + +## List State Version Outputs + +`GET /state-versions/:state_version_id/outputs` + +Listing state version outputs requires permission to read state outputs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:state_version_id` | The ID of the desired state version. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully returned a list of outputs for the given state version. | +| [404][] | [JSON API error object][] | State version not found, or user unauthorized to perform action. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 state version outputs per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/state-versions/sv-SDboVZC8TCxXEneJ/outputs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsout-xFAmCR3VkBGepcee", + "type": "state-version-outputs", + "attributes": { + "name": "fruits", + "sensitive": false, + "type": "array", + "value": [ + "apple", + "strawberry", + "blueberry", + "rasberry" + ], + "detailed_type": [ + "tuple", + [ + "string", + "string", + "string", + "string" + ] + ] + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-xFAmCR3VkBGepcee" + } + }, + { + "id": "wsout-vspuB754AUNkfxwo", + "type": "state-version-outputs", + "attributes": { + "name": "vegetables", + "sensitive": false, + "type": "array", + "value": [ + "carrots", + "potato", + "tomato", + "onions" + ], + "detailed_type": [ + "tuple", + [ + "string", + "string", + "string", + "string" + ] + ] + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-vspuB754AUNkfxwo" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/state-versions/sv-SVB5wMrDL1XUgJ4G/outputs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/state-versions/sv-SVB5wMrDL1XUgJ4G/outputs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/state-versions/sv-SVB5wMrDL1XUgJ4G/outputs?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show a State Version Output + +`GET /state-version-outputs/:state_version_output_id` + +| Parameter | Description | +| -------------------------- | ------------------------------------------- | +| `:state_version_output_id` | The ID of the desired state version output. | + +State version output IDs must be obtained from a [state version object](/terraform/enterprise/api-docs/state-versions). When requesting a state version, you can optionally add `?include=outputs` to include full details for all of that state version's outputs. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "state-version-outputs"`) | Success. | +| [404][] | [JSON API error object][] | State version output not found or user not authorized. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/state-version-outputs/wsout-J2zM24JPFbfc7bE5 +``` + +### Sample Response + +```json +{ + "data": { + "id": "wsout-J2zM24JPFbfc7bE5", + "type": "state-version-outputs", + "attributes": { + "name": "flavor", + "sensitive": false, + "type": "string", + "value": "Peanut Butter", + "detailed-type": "string" + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-J2zM24JPFbfc7bE5" + } + } +} +``` + +## Show Current State Version Outputs for a Workspace + +This endpoint allows organization users, who do not have permissions to read state versions, to fetch the latest [output values](/terraform/language/values/outputs) for a workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +-> **Note:** Sensitive values are not revealed and will be returned as `null`. To fetch an output including sensitive values see [Show a State Version Output](/terraform/enterprise/api-docs/state-version-outputs#show-a-state-version-output). + +`GET /workspaces/:workspace_id/current-state-version-outputs` + +| Parameter | Description | +| --------------- | --------------------------------------------- | +| `:workspace_id` | The ID of the workspace to read outputs from. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "state-version-outputs"`) | Successfully returned a list of outputs for the given workspace. | +| [404][] | [JSON API error object][] | State version outputs not found or user not authorized. | +| [503][] | [JSON API error object][] | State version outputs are being processed and are not ready. Retry the request. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-G4zM299PFbfc10E5/current-state-version-outputs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsout-J2zM24JPFbfc7bE5", + "type": "state-version-outputs", + "attributes": { + "name": "flavor", + "sensitive": false, + "type": "string", + "value": "Peanut Butter", + "detailed-type": "string" + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-J2zM24JPFbfc7bE5" + } + }, + { + "id": "wsout-FLzM23Gcd5f37bE5", + "type": "state-version-outputs", + "attributes": { + "name": "recipe", + "sensitive": true, + "type": "string", + "value": "Don Douglas' Peanut Butter Frenzy", + "detailed-type": "string" + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-FLzM23Gcd5f37bE5" + } + } + ] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/state-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/state-versions.mdx new file mode 100644 index 0000000000..9e8873612d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/state-versions.mdx @@ -0,0 +1,1241 @@ +--- +page_title: /state-versions API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/state-versions` endpoint to read, create, + upload, fetch, rollback, delete, and mark state versions for garbage + collection. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# State versions API reference + +## Attributes + +State version API objects represent an instance of Terraform state data, but do not directly contain the stored state. Instead, they contain information about the state, its properties, and its contents, and include one or more URLs from which the state can be downloaded. + +Some of the information returned in a state version API object might be **populated asynchronously** by HCP Terraform. This includes resources, modules, providers, and the [state version outputs](/terraform/enterprise/api-docs/state-version-outputs) associated with the state version. These values might not be immediately available after the state version is uploaded. The `resources-processed` property on the state version object indicates whether or not HCP Terraform has finished any necessary asynchronous processing. If you need to use these values, be sure to wait for `resources-processed` to become `true` before assuming that the values are in fact empty. + +| Attribute | Description | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `billable-rum-count` | Count of billable Resources Under Management (RUM). Only present for organization members on HCP Terraform RUM plans with visibility of billable RUM usage. | +| `hosted-json-state-download-url` | A URL from which you can download the state data in a [stable format](/terraform/internals/json-format) appropriate for external integrations to consume. Only available if the state was created by Terraform 1.3+. | +| `hosted-state-download-url` | A URL from which you can download the raw state data, in the format used internally by Terraform. | +| `hosted-json-state-upload-url` | A URL to which you can upload state data in a [stable format](/terraform/internals/json-format) appropriate for external integrations to consume. You can upload JSON state content once per state version. | +| `hosted-state-upload-url` | A URL to which you can upload state data in the format used Terraform uses internally. You can upload state data once per state version. | +| `modules` | Extracted information about the Terraform modules in this state data. Populated asynchronously. | +| `providers` | Extracted information about the Terraform providers used for resources in this state data. Populated asynchronously. | +| `intermediate` | A boolean flag that indicates the state version is a snapshot and not yet set as the current state version for a workspace. The last intermediate state version becomes the current state version when the workspace is unlocked. Not yet supported in Terraform Enterprise. | +| `resources` | Extracted information about the resources in this state data. Populated asynchronously. | +| `resources-processed` | A Boolean flag indicating whether HCP Terraform has finished asynchronously extracting outputs, resources, and other information about this state data. | +| `serial` | The serial number of this state instance, which increases every time Terraform creates new state in the workspace. | +| `state-version` | The version of the internal state format used for this state. Different Terraform versions read and write different format versions, but it only changes infrequently. | +| `status` | Indicates a state version's content upload [status](/terraform/enterprise/api-docs/state-versions#state-version-status). This status can be `pending`, `finalized` or `discarded`. | +| `terraform-version` | The Terraform version that created this state. Populated asynchronously. | +| `vcs-commit-sha` | The SHA of the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository. | +| `vcs-commit-url` | A link to the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository. | + +### State Version Status + +The state version status is found in `data.attributes.status`, and you can reference the following list of possible statuses. +A state version created through the API or CLI will only be listed in the UI if it is has a `finalized` status. + +| State | Description | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `pending` | Indicates that a state version has been created but the state data is not encoded within the request. Pending state versions do not contain state data and do not appear in the UI. You cannot unlock the workspace until the latest state version is finalized. | +| `finalized` | Indicates that the state version has been successfully uploaded to HCP Terraform or that the state version was created with a valid `state` attribute. | +| `discarded` | The state version was discarded because it was superseded by a newer state version before it could be uploaded. | +| `backing_data_soft_deleted` | The backing files associated with this state version are marked for garbage collection. Terraform permanently deletes backing files associated with this state version after a set number of days, but you can restore the backing data associated with it before it is permanently deleted. | +| `backing_data_permanently_deleted` | The backing files associated with this state version have been permanently deleted and can no longer be restored. | + +## Create a State Version + +> **Hands-on:** Try the [Version Remote State with the HCP Terraform API](/terraform/tutorials/cloud/cloud-state-api) tutorial to download a remote state file and use the Terraform API to create a new state version. + +`POST /workspaces/:workspace_id/state-versions` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to create the new state version in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +Creates a state version and sets it as the current state version for the given workspace. The workspace must be locked by the user creating a state version. The workspace may be locked [with the API](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) or [with the UI](/terraform/enterprise/workspaces/settings#locking). This is most useful for migrating existing state from Terraform Community edition into a new HCP Terraform workspace. + +Creating state versions requires permission to read and write state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +!> **Warning:** Use caution when uploading state to workspaces that have already performed Terraform runs. Replacing state improperly can result in orphaned or duplicated infrastructure resources. + +-> **Note:** For Free Tier organizations, HCP Terraform always retains at least the last 100 states (across all workspaces) and at least the most recent state for every workspace. Additional states beyond the last 100 are retained for six months, and are then deleted. + +-> **Note:** You cannot access this endpoint with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------------- | +| [201][] | [JSON API document][] | Successfully created a state version. | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action. | +| [409][] | [JSON API error object][] | Conflict; check the error object for more information. | +| [412][] | [JSON API error object][] | Precondition failed; check the error object for more information. | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.). | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------ | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"state-versions"`. | +| `data.attributes.serial` | integer | | The serial of the state version. Must match the serial value extracted from the raw state file. | +| `data.attributes.md5` | string | | An MD5 hash of the raw state version. | +| `data.attributes.state` | string | (nothing) | **Optional** Base64 encoded raw state file. If omitted, you must use the upload method below to complete the state version creation. The workspace may not be unlocked normally until the state version is uploaded. | +| `data.attributes.lineage` | string | (nothing) | **Optional** Lineage of the state version. Should match the lineage extracted from the raw state file. Early versions of terraform did not have the concept of lineage, so this is an optional attribute. | +| `data.attributes.json-state` | string | (nothing) | **Optional** Base64 encoded json state, as expressed by `terraform show -json`. See [JSON Output Format](/terraform/internals/json-format) for more details. | +| `data.attributes.json-state-outputs` | string | (nothing) | **Optional** Base64 encoded output values as represented by `terraform show -json` (the contents of the values/outputs key). If provided, the workspace outputs populate immediately. If omitted, HCP Terraform populates the workspace outputs from the given state after a short time. | +| `data.relationships.run.data.id` | string | (nothing) | **Optional** The ID of the run to associate with the state version. | + +### Sample Payload + +```json +{ + "data": { + "type":"state-versions", + "attributes": { + "serial": 1, + "md5": "d41d8cd98f00b204e9800998ecf8427e", + "lineage": "871d1b4a-e579-fb7c-ffdb-f0c858a647a7", + "state": "...", + "json-state": "...", + "json-state-outputs": "..." + }, + "relationships": { + "run": { + "data": { + "type": "runs", + "id": "run-bWSq4YeYpfrW4mx7" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-6fHMCom98SDXSQUv/state-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-DmoXecHePnNznaA4", + "type": "state-versions", + "attributes": { + "vcs-commit-sha": null, + "vcs-commit-url": null, + "created-at": "2018-07-12T20:32:01.490Z", + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/f55b739b-ff03-4716-b436-726466b96dc4", + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/4fde7951-93c0-4414-9a40-f3abc4bac490", + "hosted-state-upload-url": null, + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": true, + "serial": 1 + }, + "links": { + "self": "/api/v2/state-versions/sv-DmoXecHePnNznaA4" + } + } +} +``` + +## Upload State and JSON State + + You can upload state version content in the same request when creating a state version. However, we _strongly_ recommend that you upload content separately. + +`PUT https://archivist.terraform.io/v1/object/` + +HCP Terraform returns a `hosted-state-upload-url` or `hosted-json-state-upload-url` returned when you create a `state-version`. Once you upload state content, this URL is hidden on the resource and _no longer available_. + +### Sample Request + +In the below example, `@filename` is the name of Terraform state file you wish to upload. + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @filename \ + https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da +``` + +## List State Versions for a Workspace + +`GET /state-versions` + +Listing state versions requires permission to read state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ---------------------------- | -------------------------------------------------------------------------------------- | +| `filter[workspace][name]` | **Required** The name of one workspace to list versions for. | +| `filter[organization][name]` | **Required** The name of the organization that owns the desired workspace. | +| `filter[status]` | **Optional.** Filter state versions by status: `pending`, `finalized`, or `discarded`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 state versions per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/state-versions?filter%5Bworkspace%5D%5Bname%5D=my-workspace&filter%5Borganization%5D%5Bname%5D=my-organization" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + }, + { + "id": "sv-QYKf6GvNv75ZPTBr", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-01T21:40:25.941Z", + "size": 819, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + } + ], + "resources-processed": true, + "serial": 8, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/12345abcdef", + "vcs-commit-sha": "12345abcdef" + }, + "relationships": { + "run": { + "data": { + "id": "run-cVtxks6R8wsjCZMD", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-MmqMhmht6jFmLRvh", + "type": "state-version-outputs" + }, + { + "id": "wsout-Kuo9TCHg3oDLDQqa", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-QYKf6GvNv75ZPTBr" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 10 + } + } +} +``` + +## Fetch the Current State Version for a Workspace + +`GET /workspaces/:workspace_id/current-state-version` + +| Parameter | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID for the workspace whose current state version you want to fetch. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +Fetches the current state version for the given workspace. This state version +will be the input state when running terraform operations. + +Viewing state versions requires permission to read state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully returned current state version for the given workspace. | +| [404][] | [JSON API error object][] | Workspace not found, workspace does not have a current state version, or user unauthorized to perform action. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-6fHMCom98SDXSQUv/current-state-version +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "billable-rum-count": 0, + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Show a State Version + +`GET /state-versions/:state_version_id` + +Viewing state versions requires permission to read state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:state_version_id` | The ID of the desired state version. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully returned current state version for the given workspace. | +| [404][] | [JSON API error object][] | Workspace not found, workspace does not have a current state version, or user unauthorized to perform action. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/state-versions/sv-SDboVZC8TCxXEneJ +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Rollback to a Previous State Version + +`PATCH /workspaces/:workspace_id/state-versions` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to create the new state version in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +Creates a state version by duplicating the specified state version and sets it as the current state version for the given workspace. The workspace must be locked by the user creating a state version. The workspace may be locked [with the API](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) or [with the UI](/terraform/enterprise/workspaces/settings#locking). This is most useful for rolling back to a known-good state after an operation such as a Terraform upgrade didn't go as planned. + +Creating state versions requires permission to read and write state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +!> **Warning:** Use caution when rolling back to a previous state. Replacing state improperly can result in orphaned or duplicated infrastructure resources. + +-> **Note:** You cannot access this endpoint with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------- | +| [201][] | [JSON API document][] | Successfully rolled back. | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action. | +| [409][] | [JSON API error object][] | Conflict; check the error object for more information. | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.). | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------------- | ------ | ------- | -------------------------------------------------------------- | +| `data.type` | string | | Must be `"state-versions"`. | +| `data.relationships.rollback-state-version.data.id` | string | | The ID of the state version to use for the rollback operation. | + +### Sample Payload + +```json +{ + "data": { + "type":"state-versions", + "relationships": { + "rollback-state-version": { + "data": { + "type": "state-versions", + "id": "sv-bWfq4Y1YpRKW4mx7" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-6fHMCom98SDXSQUv/state-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-DmoXecHePnNznaA4", + "type": "state-versions", + "attributes": { + "created-at": "2022-11-22T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "1.3.5" + }, + "relationships": { + "rollback-state-version": { + "data": { + "id": "sv-YfmFLgTv31VZsP", + "type": "state-versions" + } + } + }, + "links": { + "self": "/api/v2/state-versions/sv-DmoXecHePnNznaA4" + } + } +} +``` + +## Mark a State Version for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/state-versions/:state_version_id/actions/soft_delete_backing_data` + +This endpoint directs Terraform Enterprise to _soft delete_ the backing files associated with this state version. Soft deletion marks the state version for garbage collection. Terraform permanently deletes state versions after a set number of days unless the state version is restored. Once a state version is soft deleted, any attempts to read the state version will fail. Refer to [State Version Status](#state-version-status) for information about all data states. + +This endpoint can only soft delete state versions that are in an [`finalized` state](#state-version-status) and are not the current state version. Otherwise, calling this endpoint results in an error. + +You must have organization owner permissions to soft delete state versions. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information about permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | ----------------------------------------------------------- | +| `:state_version_id` | The ID of the state version to mark for garbage collection. | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Terraform successfully marked the data for garbage collection. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_soft_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the state version or the user is not authorized to modify the state version. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/soft_delete_backing_data + --data {"data": {"attributes": {"delete-older-than-n-days": 23}}} +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "backing_data_soft_deleted", + "intermediate": false, + "delete-older-than-n-days": 23, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Restore a State Version Marked for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/state-versions/:state_version_id/actions/restore_backing_data` + +This endpoint directs Terraform Enterprise to restore backing files associated with this state version. This endpoint can only restore state versions that are not in a [`backing_data_permanently_deleted` state](#state-version-status). Terraform restores applicable state versions back to their `finalized` state. Otherwise, calling this endpoint results in an error. + +You must have organization owner permissions to restore state versions. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information about permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | --------------------------------------- | +| `:state_version_id` | The ID of the state version to restore. | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Terraform successfully initiated the restore process. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `finalized`. | +| [404][] | [JSON API error object][] | Terraform did not find the state version or the user is not authorized to modify the state version. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/restore_backing_data +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "uploaded", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Permanently Delete a State Version + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/state-versions/:state_version_id/actions/permanently_delete_backing_data` + +This endpoint directs Terraform Enterprise to permanently delete backing files associated with this state version. This endpoint can only permanently delete state versions that are in an [`backing_data_soft_deleted` state](#state-version-status) and are not the current state version. Otherwise, calling this endpoint results in an error. + +You must have organization owner permissions to permanently delete state versions. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information about permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | -------------------------------------------------- | +| `:state_version_id` | The ID of the state version to permanently delete. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Terraform deleted the data permanently. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_permanently_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the state version or the user is not authorized to modify the state version data. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/permanently_delete_backing_data +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "backing_data_permanently_deleted", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## List State Version Outputs + +The output values from a state version are also available via the API. For details, see the [state version outputs documentation.](/terraform/enterprise/api-docs/state-version-outputs#list-state-version-outputs) + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `created_by` - The user that created the state version. For state versions created via a run executed by HCP Terraform, this is an internal user account. +- `run` - The run that created the state version, if applicable. +- `run.created_by` - The user that manually triggered the run, if applicable. +- `run.configuration_version` - The configuration version used in the run. +- `outputs` - The parsed outputs for this state version. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-access.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-access.mdx new file mode 100644 index 0000000000..8d873b5c3f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-access.mdx @@ -0,0 +1,433 @@ +--- +page_title: /team-workspaces API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/team-workspaces` endpoint to manage team + access to a workspace. Read, add, update, and remove a team's access to + workspaces. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Team access API reference + + + +-> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). + + + +The team access APIs are used to associate a team to permissions on a workspace. A single `team-workspace` resource contains the relationship between the Team and Workspace, including the privileges the team has on the workspace. + +## Resource permissions + +A `team-workspace` resource represents a team's local permissions on a specific workspace. Teams can also have organization-level permissions that grant access to workspaces. HCP Terraform uses the more restrictive access level. For example, a team with the **Manage workspaces** permission enabled has admin access on all workspaces, even if their `team-workspace` on a particular workspace only grants read access. For more information, refer to [Managing Workspace Access](/terraform/enterprise/users-teams-organizations/teams/manage#managing-workspace-access). + +Any member of an organization can view team access relative to their own team memberships, including secret teams of which they are a member. Organization owners and workspace admins can modify team access or view the full set of secret team accesses. The organization token and the owners team token can act as an owner on these endpoints. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +## List Team Access to a Workspace + +`GET /team-workspaces` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | ---------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace not found or user unauthorized to perform action | + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[workspace][id]` | **Required.** The workspace ID to list team access for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | +| `page[number]` | **Optional.** | +| `page[size]` | **Optional.** | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + "https://app.terraform.io/api/v2/team-workspaces?filter%5Bworkspace%5D%5Bid%5D=ws-XGA52YVykdTgryTN" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tws-19iugLwoNgtWZbKP", + "type": "team-workspaces", + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "none", + "state-versions": "none", + "sentinel-mocks": "none", + "workspace-locking": false, + "run-tasks": false + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-19iugLwoNgtWZbKP" + } + } + ] +} +``` + +## Show a Team Access relationship + +`GET /team-workspaces/:id` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Team access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/workspace relationship. Obtain this from the [list team access action](#list-team-access-to-a-workspace) described above. | + +-> **Note:** As mentioned in [Add Team Access to a Workspace](#add-team-access-to-a-workspace) and [Update Team Access +to a Workspace](#update-team-access-to-a-workspace), several permission attributes are not editable unless `access` is +set to `custom`. When access is `read`, `plan`, `write`, or `admin`, these attributes are read-only and reflect the +implicit permissions granted to the current access level. + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/team-workspaces/tws-s68jV4FWCDwWvQq8 +``` + +### Sample Response + +```json +{ + "data": { + "id": "tws-s68jV4FWCDwWvQq8", + "type": "team-workspaces", + "attributes": { + "access": "write", + "runs": "apply", + "variables": "write", + "state-versions": "write", + "sentinel-mocks": "read", + "workspace-locking": true, + "run-tasks": false + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-s68jV4FWCDwWvQq8" + } + } +} +``` + +## Add Team Access to a Workspace + +`POST /team-workspaces` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | ------------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace or Team not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"team-workspaces"`. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `plan`, `write`, `admin`, or `custom`. | +| `data.attributes.runs` | string | "read" | If `access` is `custom`, the permission to grant for the workspace's runs. Can only be used when `access` is `custom`. Valid values include `read`, `plan`, or `apply`. | +| `data.attributes.variables` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's variables. Can only be used when `access` is `custom`. Valid values include `none`, `read`, or `write`. | +| `data.attributes.state-versions` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's state versions. Can only be used when `access` is `custom`. Valid values include `none`, `read-outputs`, `read`, or `write`. | +| `data.attributes.sentinel-mocks` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's Sentinel mocks. Can only be used when `access` is `custom`. Valid values include `none`, or `read`. | +| `data.attributes.workspace-locking` | boolean | false | If `access` is `custom`, the permission granting the ability to manually lock or unlock the workspace. Can only be used when `access` is `custom`. | +| `data.attributes.run-tasks` | boolean | false | If `access` is `custom`, this permission allows the team to manage run tasks within the workspace. | +| `data.relationships.workspace.data.type` | string | | Must be `workspaces`. | +| `data.relationships.workspace.data.id` | string | | The workspace ID to which the team is to be added. | +| `data.relationships.team.data.type` | string | | Must be `teams`. | +| `data.relationships.team.data.id` | string | | The ID of the team to add to the workspace. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "none", + "state-versions": "read-outputs", + "plan-outputs": "none", + "sentinel-mocks": "read", + "workspace-locking": false, + "run-tasks": false + }, + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-XGA52YVykdTgryTN" + } + }, + "team": { + "data": { + "type": "teams", + "id": "team-DBycxkdQrGFf5zEM" + } + } + }, + "type": "team-workspaces" + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/team-workspaces +``` + +### Sample Response + +```json +{ + "data": { + "id": "tws-sezDAcCYWLnd3xz2", + "type": "team-workspaces", + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "none", + "state-versions": "read-outputs", + "sentinel-mocks": "read", + "workspace-locking": false, + "run-tasks": false + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-sezDAcCYWLnd3xz2" + } + } +} +``` + +## Update Team Access to a Workspace + +`PATCH /team-workspaces/:id` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +| Parameter | | | Description | +| ----------------------------------- | ------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | | | The ID of the team/workspace relationship. Obtain this from the [list team access action](#list-team-access-to-a-workspace) described above. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `plan`, `write`, `admin`, or `custom`. | +| `data.attributes.runs` | string | "read" | If `access` is `custom`, the permission to grant for the workspace's runs. Can only be used when `access` is `custom`. | +| `data.attributes.variables` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's variables. Can only be used when `access` is `custom`. | +| `data.attributes.state-versions` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's state versions. Can only be used when `access` is `custom`. | +| `data.attributes.sentinel-mocks` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's Sentinel mocks. Can only be used when `access` is `custom`. | +| `data.attributes.workspace-locking` | boolean | false | If `access` is `custom`, the permission granting the ability to manually lock or unlock the workspace. Can only be used when `access` is `custom`. | +| `data.attributes.run-tasks` | boolean | false | If `access` is `custom`, this permission allows the team to manage run tasks within the workspace. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/team-workspaces/tws-s68jV4FWCDwWvQq8 +``` + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "access": "custom", + "state-versions": "none" + } + } +} +``` + +### Sample Response + +```json +{ + "data": { + "id": "tws-s68jV4FWCDwWvQq8", + "type": "team-workspaces", + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "write", + "state-versions": "none", + "sentinel-mocks": "read", + "workspace-locking": true, + "run-tasks": true + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-s68jV4FWCDwWvQq8" + } + } +} +``` + +## Remove Team Access to a Workspace + +`DELETE /team-workspaces/:id` + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | | The Team Access was successfully destroyed | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/workspace relationship. Obtain this from the [list team access action](#list-team-access-to-a-workspace) described above. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/team-workspaces/tws-sezDAcCYWLnd3xz2 +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-members.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-members.mdx new file mode 100644 index 0000000000..b3cf58069b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-members.mdx @@ -0,0 +1,249 @@ +--- +page_title: /relationships API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/relationships` endpoints to add and + remove users from teams using an account or organization membership ID. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Team membership API reference + + + +-> **Note:** Team management is available in HCP Terraform **Standard** Edition. Free organizations can also use this API, but can only manage membership of their owners team. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). + + + +The Team Membership API is used to add or remove users from teams. The [Team API](/terraform/enterprise/api-docs/teams) is used to create or destroy teams. + +## Organization Membership + +-> **Note:** To add users to a team, they must first receive and accept the invitation to join the organization by email. This process ensures that you do not accidentally add the wrong person by mistyping a username. Refer to [the Organization Memberships API documentation](/terraform/enterprise/api-docs/organization-memberships) for more information. + +## Add a User to Team (With user ID) + +This method adds multiple users to a team using the user ID. Both users and teams must already exist. + +`POST /teams/:team_id/relationships/users` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------------------------------ | +| `data[].type` | string | | Must be `"users"`. | +| `data[].id` | string | | The ID of the user you want to add to this team. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "users", + "id": "myuser1" + }, + { + "type": "users", + "id": "myuser2" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/257525/relationships/users +``` + +## Add a User to Team (With organization membership ID) + +This method adds multiple users to a team using the organization membership ID. Unlike the user ID method, the user only needs an invitation to the organization. + +`POST /teams/:team_id/relationships/organization-memberships` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | -------------------------------------------------- | +| `data[].type` | string | | Must be `"organization-memberships"`. | +| `data[].id` | string | | The organization membership ID of the user to add. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "organization-memberships", + "id": "ou-nX7inDHhmC3quYgy" + }, + { + "type": "organization-memberships", + "id": "ou-tTJph1AQVK5ZmdND" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/257525/relationships/organization-memberships +``` + +## Delete a User from Team (With user ID) + +This method removes multiple users from a team using the user ID. Both users and teams must already exist. This method only removes a user from this team. It does not delete that user overall. + +`DELETE /teams/:team_id/relationships/users` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | -------------------------------------------- | +| `data[].type` | string | | Must be `"users"`. | +| `data[].id` | string | | The ID of the user to remove from this team. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "users", + "id": "myuser1" + }, + { + "type": "users", + "id": "myuser2" + } + ] +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/257525/relationships/users +``` + +## Delete a User from Team (With organization membership ID) + +This method removes multiple users from a team using the organization membership ID. This method only removes a user from this team. It does not delete that user overall. + +`DELETE /teams/:team_id/relationships/organization-memberships` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------- | +| `data[].type` | string | | Must be `"organization-memberships"`. | +| `data[].id` | string | | The organization membership ID of the user to remove. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "organization-memberships", + "id": "ou-nX7inDHhmC3quYgy" + }, + { + "type": "organization-memberships", + "id": "ou-tTJph1AQVK5ZmdND" + } + ] +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/257525/relationships/organization-memberships +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-tokens.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-tokens.mdx new file mode 100644 index 0000000000..ed5921623e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/team-tokens.mdx @@ -0,0 +1,299 @@ +--- +page_title: /teams/authentication-token API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/teams/authentication-token` endpoint to + generate, delete, and list a team's API tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Team tokens API reference + +Team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens. + +## Generate a new team token + +Generates a new team token and overrides existing token if one exists. + +| Method | Path | +| :----- | :----------------------------------- | +| POST | /teams/:team_id/authentication-token | + +This endpoint returns the secret text of the new authentication token. You can only access this token when you create it and can not recover it later. + +### Parameters + +- `:team_id` (`string: `) - specifies the team ID for generating the team token + +### Request body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ---------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"authentication-token"`. | +| `data.attributes.expired-at` | string | `null` | The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | + +### Sample payload + +```json +{ + "data": { + "type": "authentication-token", + "attributes": { + "expired-at": "2023-04-06T12:00:00.000Z" + } + } +} +``` + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-token +``` + +### Sample response + +```json +{ + "data": { + "id": "4111797", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": null, + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-Y7RyjccPVBKVEdp7", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-62goNpx1ThQf689e", + "type": "users" + } + } + } + } +} +``` + +## Delete the team token + +| Method | Path | +| :----- | :----------------------------------- | +| DELETE | /teams/:team_id/authentication-token | + +### Parameters + +- `:team_id` (`string: `) - specifies the team_id from which to delete the token + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-token +``` + +## List team tokens + +Lists the [team tokens](/terraform/enterprise/users-teams-organizations/teams#api-tokens) in an organization. + +`GET organizations/:organization_name/team-tokens` + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------- | +| `:organization_name` | The name of the organization whose team tokens you want to list. | + +This endpoint returns object metadata and does not include secret authentication details of tokens. You can only view a token when you create it and cannot recover it later. + +By default, this endpoint returns tokens by ascending expiration date. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ---------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-tokens"`) | The request was successful. | +| [200][] | Empty [JSON API document][] | The specified organization has no team tokens. | +| [404][] | [JSON API error object][] | Organization not found. | + +### Query parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters) and searching with the `q` parameter. Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 tokens per page. | +| `q` | **Optional.** A search query string. You can search for a team authentication token using the team name. | +| `sort` | **Optional.** Allows sorting the team tokens by `"team-name"`, `"created-by"`, `"expired-at"`, and `"last-used-at"`. Prepending a hyphen to the sort parameter reverses the order. For example, `"-team-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order ascending. | + +### Sample response + +```json +{ + "data": [ + { + "id": "at-TLhN8cc6ro6qYDvp", + "type": "authentication-tokens", + "attributes": { + "created-at": "2024-06-19T18:28:25.267Z", + "last-used-at": null, + "description": null, + "token": null, + "expired-at": "2024-07-19T18:28:25.030Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-Y7RyjccPVBKVEdp7", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629sszLJBpY", + "type": "users" + } + } + } + }, + { + "id": "at-qfc2wqqJ1T5sCamM", + "type": "authentication-tokens", + "attributes": { + "created-at": "2024-06-19T18:44:44.051Z", + "last-used-at": null, + "description": null, + "token": null, + "expired-at": "2024-07-19T18:44:43.818Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-58pFiBffTLMxLphR", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629hhzLJBpY", + "type": "users" + } + } + } + }, + ] +} +``` + +## Show a team token + +Use this endpoint to display a [team token](/terraform/enterprise/users-teams-organizations/teams#api-tokens) for a particular team. + +`GET /teams/:team-id/authentication-token` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team-id` | The ID of the Team. | + +You can also fetch a team token directly by using the token's ID with the `authentication-tokens/` endpoint. + +`GET /authentication-tokens/:token-id` + +| Parameter | Description | +| ----------- | ------------------------- | +| `:token-id` | The ID of the Team Token. | + +The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Token not found, or unauthorized to view the Team Token | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/teams/team-6yEmxNAhaoQLH1Da/authentication-token +``` + +### Sample response + +```json +{ + "data": { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2023-11-25T22:31:30.624Z", + "last-used-at": "2023-11-26T20:34:59.487Z", + "description": null, + "token": null, + "expired-at": "2024-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-LnREdjodkvZFGdXL", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/teams.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/teams.mdx new file mode 100644 index 0000000000..1f96792b02 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/teams.mdx @@ -0,0 +1,466 @@ +--- +page_title: /teams API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/teams` endpoint to read, create, update, + and delete teams. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Teams API reference + +The Teams API is used to create, edit, and destroy teams as well as manage a team's organization-level permissions. The [Team Membership API](/terraform/enterprise/api-docs/team-members) is used to add or remove users from a team. Use the [Team Access API](/terraform/enterprise/api-docs/team-access) to associate a team with privileges on an individual workspace. + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +Any member of an organization can view visible teams and any secret teams they are a member of. Only organization owners can modify teams or view the full set of secret teams. The organization token and the owners team token can act as an owner on these endpoints. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Organization Membership + +-> **Note:** Users must be invited to join organizations before they can be added to teams. See [the Organization Memberships API documentation](/terraform/enterprise/api-docs/organization-memberships) for more information. Invited users who have not yet accepted will not appear in Teams API responses. + +## List teams + +`GET organizations/:organization_name/teams` + +| Parameter | Description | +| -------------------- | ------------------------------------------------ | +| `:organization_name` | The name of the organization to list teams from. | + +The response may identify HashiCorp API service accounts, for example `api-team_XXXXXX`, as a members of a team. However, API service accounts do not appear in the UI. As a result, there may be differences between the number of team members reported by the UI and the API. For example, the UI may report `0` members on a team when and the API reports `1`. + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** Allows querying a list of teams by name. This search is case-insensitive. | +| `filter[names]` | **Optional.** If specified, restricts results to a team with a matching name. If multiple comma separated values are specified, teams matching any of the names are returned. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 teams per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/teams +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. +The `allow-member-token-management` attribute is set to `false` for Terraform Enterprise versions older than 202408-1. + +```json +{ + "data": [ + { + "id": "team-6p5jTwJQXwqZBncC", + "type": "teams", + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "users-count": 0, + "visibility": "organization", + "allow-member-token-management": true, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "organization-access": { + "manage-policies": true, + "manage-policy-overrides": false, + "manage-run-tasks": true, + "manage-workspaces": false, + "manage-vcs-settings": false, + "manage-agent-pools": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": false + } + }, + "relationships": { + "users": { + "data": [] + }, + "authentication-token": { + "meta": {} + } + }, + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + } + } + ] +} +``` + +## Create a Team + +`POST /organizations/:organization_name/teams` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create the team in. The organization must already exist in the system, and the user must have permissions to create new teams. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "teams"`) | Successfully created a team | +| [400][] | [JSON API error object][] | Invalid `include` parameter | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during team creation | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +-> **Note:** You cannot set `manage-workspaces` to `false` when setting `manage-projects` to `true`, since project permissions cascade down to workspaces. This is also the case for `read-workspaces` and `read-projects`. If `read-projects` is `true`, `read-workspaces` must be `true` as well. + +| Key path | Type | Default | Description | +| ------------------------------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"teams"`. | +| `data.attributes.name` | string | | The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.sso-team-id` | string | (nothing) | The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or in HCP Terraform. | +| `data.attributes.organization-access` | object | (nothing) | Settings for the team's organization access. This object can include the `manage-policies`, `manage-policy-overrides`, `manage-run-tasks`, `manage-workspaces`, `manage-vcs-settings`, `manage-agent-pools`, `manage-providers`, `manage-modules`, `manage-projects`, `read-projects`, `read-workspaces`, `manage-membership`, `manage-teams`, and `manage-organization-access` properties with boolean values. All properties default to `false`. | +| `data.attributes.visibility` | string | `"secret"` | The team's visibility. Must be `"secret"` or `"organization"` (visible). | + +### Sample Payload + +```json +{ + "data": { + "type": "teams", + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "organization-access": { + "manage-workspaces": true + } + } + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/teams +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. + +```json +{ + "data": { + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "organization-access": { + "manage-policies": false, + "manage-policy-overrides": false, + "manage-run-tasks": false, + "manage-vcs-settings": false, + "manage-agent-pools": false, + "manage-workspaces": true, + "manage-providers": false, + "manage-modules": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": true, + "manage-membership": false, + "manage-teams": false, + "manage-organization-access": false + }, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "users-count": 0, + "visibility": "secret", + "allow-member-token-management": true + }, + "id": "team-6p5jTwJQXwqZBncC", + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + }, + "relationships": { + "authentication-token": { + "meta": {} + }, + "users": { + "data": [] + } + }, + "type": "teams" + } +} +``` + +## Show Team Information + +`GET /teams/:team_id` + +| Parameter | Description | +| ---------- | ------------------------ | +| `:team_id` | The team ID to be shown. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. + +```json +{ + "data": { + "id": "team-6p5jTwJQXwqZBncC", + "type": "teams", + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "users-count": 0, + "visibility": "organization", + "allow-member-token-management": true, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "organization-access": { + "manage-policies": true, + "manage-policy-overrides": false, + "manage-run-tasks": true, + "manage-workspaces": false, + "manage-vcs-settings": false, + "manage-agent-pools": false, + "manage-providers": false, + "manage-modules": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": false, + "manage-membership": false, + "manage-teams": false, + "manage-organization-access": false + } + }, + "relationships": { + "users": { + "data": [] + }, + "authentication-token": { + "meta": {} + } + }, + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + } + } +} +``` + +## Update a Team + +`PATCH /teams/:team_id` + +| Parameter | Description | +| ---------- | -------------------------- | +| `:team_id` | The team ID to be updated. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "teams"`) | Successfully created a team | +| [400][] | [JSON API error object][] | Invalid `include` parameter | +| [404][] | [JSON API error object][] | Team not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during team creation | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +-> **Note:** You cannot set `manage-workspaces` to `false` when setting `manage-projects` to `true`, since project permissions cascade down to workspaces. This is also the case for `read-workspaces` and `read-projects`. If `read-projects` is `true`, `read-workspaces` must be `true` as well. + +| Key path | Type | Default | Description | +| --------------------------------------------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"teams"`. | +| `data.attributes.name` | string | (previous value) | The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.sso-team-id` | string | (previous value) | The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or in HCP Terraform. | +| `data.attributes.organization-access` | object | (previous value) | Settings for the team's organization access. This object can include the `manage-policies`, `manage-policy-overrides`, `manage-run-tasks`, `manage-workspaces`, `manage-vcs-settings`, `manage-agent-pools`, `manage-providers`, `manage-modules`, `manage-projects`, `read-projects`, `read-workspaces`, `manage-membership`, `manage-teams`, and `manage-organization-access` properties with boolean values. All properties default to `false`. | +| `data.attributes.visibility` | string | (previous value) | The team's visibility. Must be `"secret"` or `"organization"` (visible). | +| `data.attributes.allow-team-token-management` | boolean | (previous value) | The ability to enable and disable team token management for a team. Defaults to true. | + +### Sample Payload + +```json +{ + "data": { + "type": "teams", + "attributes": { + "visibility": "organization", + "allow-member-token-management": true, + "organization-access": { + "manage-vcs-settings": true + } + } + } +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. + +```json +{ + "data": { + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "organization-access": { + "manage-policies": false, + "manage-policy-overrides": false, + "manage-run-tasks": true, + "manage-vcs-settings": true, + "manage-agent-pools": false, + "manage-workspaces": true, + "manage-providers": false, + "manage-modules": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": true, + "manage-membership": false, + "manage-teams": false, + "manage-organization-access": false + }, + "visibility": "organization", + "allow-member-token-management": true, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "users-count": 0 + }, + "id": "team-6p5jTwJQXwqZBncC", + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + }, + "relationships": { + "authentication-token": { + "meta": {} + }, + "users": { + "data": [] + } + }, + "type": "teams" + } +} +``` + +## Delete a Team + +`DELETE /teams/:team_id` + +| Parameter | Description | +| ---------- | -------------------------- | +| `:team_id` | The team ID to be deleted. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `users` (`string`) - Returns the full user record for every member of a team. +- `organization-memberships` (`string`) - Returns the full organization membership record for every member of a team. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/user-tokens.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/user-tokens.mdx new file mode 100644 index 0000000000..a26352ea06 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/user-tokens.mdx @@ -0,0 +1,286 @@ +--- +page_title: /users/authentication-tokens API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/users/authentication-tokens` endpoint to + read, create, and destroy user-specific API tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# User tokens API reference + +## List User Tokens + +`GET /users/:user_id/authentication-tokens` + +| Parameter | Description | +| ---------- | ------------------- | +| `:user_id` | The ID of the User. | + +Use the [Account API](/terraform/enterprise/api-docs/account) to find your own user ID. + +The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later. + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only return useful data for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [200][] | Empty [JSON API document][] (no type) | User has no authentication tokens, or request was made by someone other than the user | +| [404][] | [JSON API error object][] | User not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | --------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 user tokens per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/users/user-MA4GL63FmYRpSFxa/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "at-QmATJea6aWj1xR2t", + "type": "authentication-tokens", + "attributes": { + "created-at": "2018-11-06T22:56:10.203Z", + "last-used-at": null, + "description": null, + "token": null, + "expired-at": null + }, + "relationships": { + "created-by": { + "data": null + } + } + }, + { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2018-11-25T22:31:30.624Z", + "last-used-at": "2018-11-26T20:27:54.931Z", + "description": "api", + "token": null, + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } + ] +} +``` + +## Show a User Token + +`GET /authentication-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------- | +| `:id` | The ID of the User Token. | + +The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later. + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only return useful data for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | User Token not found, or unauthorized to view the User Token | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` + +### Sample Response + +```json +{ + "data": { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2018-11-25T22:31:30.624Z", + "last-used-at": "2018-11-26T20:34:59.487Z", + "description": "api", + "token": null, + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` + +## Create a User Token + +`POST /users/:user_id/authentication-tokens` + +| Parameter | Description | +| ---------- | ------------------- | +| `:user_id` | The ID of the User. | + +Use the [Account API](/terraform/enterprise/api-docs/account) to find your own user ID. + +This endpoint returns the secret text of the created authentication token. A token is only shown upon creation, and cannot be recovered later. + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only create new tokens for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | User not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during User Token creation | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"authentication-tokens"`. | +| `data.attributes.description` | string | | The description for the User Token. | +| `data.attributes.expired-at` | string | `null` | The UTC date and time that the User Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | + +### Sample Payload + +```json +{ + "data": { + "type": "authentication-tokens", + "attributes": { + "description":"api", + "expired-at": "2023-04-06T12:00:00.000Z" + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/users/user-MA4GL63FmYRpSFxa/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": { + "id": "at-MKD1X3i4HS3AuD41", + "type": "authentication-tokens", + "attributes": { + "created-at": "2018-11-26T20:48:35.054Z", + "last-used-at": null, + "description": "api", + "token": "6tL24nM38M7XWQ.atlasv1.KmWckRfzeNmUVFNvpvwUEChKaLGznCSD6fPf3VPzqMMVzmSxFU0p2Ibzpo2h5eTGwPU", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` + +## Destroy a User Token + +`DELETE /authentication-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------------------ | +| `:id` | The ID of the User Token to destroy. | + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only delete tokens for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | Empty response | The User Token was successfully destroyed | +| [404][] | [JSON API error object][] | User Token not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/users.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/users.mdx new file mode 100644 index 0000000000..4c8625e8c7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/users.mdx @@ -0,0 +1,102 @@ +--- +page_title: /users API reference for Terraform Enterprise +description: Use the Terraform Enterprise API's `/users` endpoint to read a user's details. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Users API reference + +HCP Terraform's user objects do not contain any identifying information about a user, other than their HCP Terraform username and avatar image; they are intended for displaying names and avatars in contexts that refer to a user by ID, like lists of team members or the details of a run. Most of these contexts can already include user objects via an `?include` parameter, so you shouldn't usually need to make a separate call to this endpoint. + +## Show a User + +Shows details for a given user. + +`GET /users/:user_id` + +| Parameter | Description | +| ---------- | --------------------------- | +| `:user_id` | The ID of the desired user. | + +To find the ID that corresponds to a given username, you can request a [team object](/terraform/enterprise/api-docs/teams) for a team that user belongs to, specify `?include=users` in the request, and look for the user's name in the included list of user objects. + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "users"`) | The request was successful | +| [401][] | [JSON API error object][] | Unauthorized | +| [404][] | [JSON API error object][] | User not found, or unauthorized to view the user | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/users/user-MA4GL63FmYRpSFxa +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "hcp_sso", + "avatar-url": "https://www.gravatar.com/avatar/fa1f0c9364253d351bf1c7f5c534cd40?s=100&d=mm", + "v2-only": true, + "permissions": { + "can-create-organizations": false, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-MA4GL63FmYRpSFxa/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-MA4GL63FmYRpSFxa" + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/variable-sets.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/variable-sets.mdx new file mode 100644 index 0000000000..8bca544f1a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/variable-sets.mdx @@ -0,0 +1,1018 @@ +--- +page_title: /varsets API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/varsets` endpoint to read, create, + update, and delete variable sets, and apply or remove variable sets from + workspaces and projects. +source: terraform-docs-common +--- + +# Variable sets API reference + +A [variable set](/terraform/enterprise/workspaces/variables#scope) is a resource that allows you to reuse the same variables across multiple workspaces and projects. For example, you could define a variable set of provider credentials and automatically apply it to a selection of workspaces, all workspaces in a project, or all workspaces in an organization. + +Projects and organizations can both own variable sets. The owner of a variable set can determine the precedence of that set. Refer to [**Manage variable sets**](/terraform/enterprise/workspaces/variables/managing-variables#permissions) for more details on variable set permissions. + +To view the variables applied from a variable set on a particular workspace, you must have [**Read** variables permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) on that workspace. + +## Create a Variable Set + +`POST organizations/:organization_name/varsets` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------- | +| `:organization_name` | The name of the organization the variable set belongs to. | + +### Request Body + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------- | ------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.name` | string | | The name of the variable set. | +| `data.attributes.description` | string | `""` | Text displayed in the UI to contextualize the variable set and its purpose. | +| `data.attributes.global` | boolean | `false` | When true, HCP Terraform automatically applies the variable set to all current and future workspaces in the organization. | +| `data.attributes.priority` | boolean | `false` | When true, the variables in the set override any other variable values with a more specific scope, including values set on the command line. | +| `data.relationships.workspaces` | array | `[]` | Array of references to workspaces that the variable set should be assigned to. | +| `data.relationships.projects` | array | `[]` | Array of references to projects that the variable set should be assigned to. | +| `data.relationships.vars` | array | `[]` | Array of complete variable definitions that comprise the variable set. | +| `data.relationships.parent` | object | Organization that the variable set belongs to | The parent that owns this variable set. If the parent is a project, `data.attributes.global` must be `false`. | +| `data.relationships.parent.data.type` | string | `"organizations"` | The resource type of the parent that owns this variable set. Valid values are `organizations` or `projects`. | +| `data.relationships.parent.data.id` | string | Name of organization that the variable set belongs to. | The ID of the parent that owns the variable set. For organizations, use name instead of ID. | + +HCP Terraform does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to create a global variable set that contains conflicting variables. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully added variable set | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + }, + "relationships": { + "workspaces": { + "data": [ + { + "id": "ws-z6YvbWEYoE168kpq", + "type": "workspaces" + } + ] + }, + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + }, + "parent": { + "data": { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/varsets +``` + +### Sample Response + +```json +{ + "data": { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + }, + "relationships": { + "workspaces": { + "data": [ + { + "id": "ws-z6YvbWEYoE168kpq", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + ] + }, + "vars": { + "data": [ + { + "id": "var-Nh0doz0hzj9hrm34qq", + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + }, + "parent": { + "data": { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + } + } + } +} +``` + +## Update a Variable Set + +`PUT/PATCH varsets/:varset_id` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +HCP Terraform does not allow global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to create a global variable set that contains conflicting variables. + +HCP Terraform does not allow you to change the parent organization or project of a variable set. Instead, you must delete the variable set and recreate it in the desired organization or project. + +### Request Body + +| Key path | Type | Default | Description | +| ------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.name` | string | | The name of the variable set. | +| `data.attributes.description` | string | | Text displayed in the UI to contextualize the variable set and its purpose. | +| `data.attributes.global` | boolean | | When true, HCP Terraform automatically applies the variable set to all current and future workspaces in the organization. | +| `data.attributes.priority` | boolean | `false` | When true, the variables in the set override any other variable values set with a more specific scope, including values set on the command line. | +| `data.relationships.workspaces` | array | | **Optional** Array of references to workspaces that the variable set should be assigned to. Sending an empty array clears all workspace assignments. | +| `data.relationships.projects` | array | | **Optional** Array of references to projects that the variable set should be assigned to. Sending an empty array clears all project assignments. | +| `data.relationships.vars` | array | | **Optional** Array of complete variable definitions to add to the variable set. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------ | +| [200][] | [JSON API document][] | Successfully updated variable set | +| [404][] | [JSON API error object][] | Organization or variable set not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse. Now global!", + "global": true, + "priority": true, + }, + "relationships": { + "workspaces": { + "data": [ + { + "id": "ws-FRFwkYoUoGn1e34b", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + ] + }, + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv +``` + +### Sample Response + +```json +{ + "data": { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse. Now global!", + "global": true, + "priority": true + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-FRFwkYoUoGn1e34b", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + ] + }, + "vars": { + "data": [ + { + "id": "var-Nh0doz0hzj9hrm34qq", + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + }, + "parent": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` + +## Delete a Variable Set + +`DELETE varsets/:varset_id` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv +``` + +On success, this endpoint responds with no content. + +## Show Variable Set + +Fetch details about the specified variable set. + +`GET varsets/:varset_id` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv +``` + +### Sample Response + +```json +{ + "data": { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + "updated-at": "2023-03-06T21:48:33.588Z", + "var-count": 5, + "workspace-count": 2, + "project-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "vars": { + "data": [ + { + "id": "var-mMqadSCxZtrQJAv8", + "type": "vars" + }, + { + "id": "var-hFxUUKSk35QMsRVH", + "type": "vars" + }, + { + "id": "var-fkd6N48tXRmoaPxH", + "type": "vars" + }, + { + "id": "var-abcbBMBMWcZw3WiV", + "type": "vars" + }, + { + "id": "var-vqvRKK1ZoqQCiMwN", + "type": "vars" + } + ] + }, + "workspaces": { + "data": [ + { + "id": "ws-UohFdKAHUGsQ8Dtf", + "type": "workspaces" + }, + { + "id": "ws-XhGhaaCrsx9ATson", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-1JMwvPHFsdpsPhnt", + "type": "projects" + }, + { + "id": "prj-SLDGqbYqELXE1obp", + "type": "projects" + } + ] + }, + "parent": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` + +## List Variable Sets + +List all variable sets for an organization. + +`GET organizations/:organization_name/varsets` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------- | +| `:organization_name` | The name of the organization the variable sets belong to | + +List all variable sets for a project. This includes global variable sets from the project's organization. + +`GET projects/:project_id/varsets` + +| Parameter | Description | +| ------------- | -------------- | +| `:project_id` | The project ID | + +List all variable sets for a workspace. This includes global variable sets from the workspace's organization and variable sets +attached to the project this workspace is contained within. + +`GET workspaces/:workspace_id/varsets` + +| Parameter | Description | +| --------------- | ---------------- | +| `:workspace_id` | The workspace ID | + +### Query Parameters + +All list endpoints support pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters) and searching with the `q` parameter. Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 varsets per page. | +| `q` | **Optional.** A search query string. You can search for a variable set using its name. | + +### Sample Response + +```json +{ + "data": [ + { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + "updated-at": "2023-03-06T21:48:33.588Z", + "var-count": 5, + "workspace-count": 2, + "project-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "vars": { + "data": [ + { + "id": "var-mMqadSCxZtrQJAv8", + "type": "vars" + }, + { + "id": "var-hFxUUKSk35QMsRVH", + "type": "vars" + }, + { + "id": "var-fkd6N48tXRmoaPxH", + "type": "vars" + }, + { + "id": "var-abcbBMBMWcZw3WiV", + "type": "vars" + }, + { + "id": "var-vqvRKK1ZoqQCiMwN", + "type": "vars" + } + ] + }, + "workspaces": { + "data": [ + { + "id": "ws-UohFdKAHUGsQ8Dtf", + "type": "workspaces" + }, + { + "id": "ws-XhGhaaCrsx9ATson", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-1JMwvPHFsdpsPhnt", + "type": "projects" + }, + { + "id": "prj-SLDGqbYqELXE1obp", + "type": "projects" + } + ] + }, + "parent": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/varsets?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/varsets?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/varsets?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +### Variable Relationships + +## Add Variable + +`POST varsets/:varset_external_id/relationships/vars` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | | The description of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true, variable is not visible in the UI. | + +HCP Terraform does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to add a conflicting variable to a global variable set. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully added variable to variable set | +| [404][] | [JSON API error object][] | Variable set not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-4q8f7H0NHG733bBH/relationships/vars +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +## Update a Variable in a Variable Set + +`PATCH varsets/:varset_id/relationships/vars/:var_id` + +| Parameter | Description | +| ------------ | -------------------------------- | +| `:varset_id` | The variable set ID | +| `:var_id` | The ID of the variable to delete | + +HCP Terraform does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to add a conflicting variable to a global variable set. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully updated variable for variable set | +| [404][] | [JSON API error object][] | Variable set not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "new cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-4q8f7H0NHG733bBH/relationships/vars/var-EavQ1LztoRTQHSNT +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "new cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +## Delete a Variable in a Variable Set + +`DELETE varsets/:varset_id/relationships/vars/:var_id` + +| Parameter | Description | +| ------------ | -------------------------------- | +| `:varset_id` | The variable set ID | +| `:var_id` | The ID of the variable to delete | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/varsets/varset-4q8f7H0NHG733bBH/relationships/vars/var-EavQ1LztoRTQHSNT +``` + +On success, this endpoint responds with no content. + +## List Variables in a Variable Set + +`GET varsets/:varset_id/relationships/vars` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Sample Response + +```json +{ + "data": [ + { + "id": "var-134r1k34nj5kjn", + "type": "vars", + "attributes": { + "key": "F115037558b045dd82da40b089e5db745", + "value": "1754288480dfd3060e2c37890422905f", + "sensitive": false, + "category": "terraform", + "hcl": false, + "created-at": "2021-10-29T18:54:29.379Z", + "description": "" + }, + "relationships": { + "varset": { + "data": { + "id": "varset-992UMULdeDuebi1x", + "type": "varsets" + }, + "links": { "related": "/api/v2/varsets/1" } + } + }, + "links": { "self": "/api/v2/vars/var-BEPU9NjPVCiCfrXj" } + } + ], + "links": { + "self": "app.terraform.io/app/varsets/varset-992UMULdeDuebi1x/vars", + "first": "app.terraform.io/app/varsets/varset-992UMULdeDuebi1x/vars?page=1", + "prev": null, + "next": null, + "last": "app.terraform.io/app/varsets/varset-992UMULdeDuebi1x/vars?page=1" + } +} +``` + +## Apply Variable Set to Workspaces + +Accepts a list of workspaces to add the variable set to. + +`POST varsets/:varset_id/relationships/workspaces` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | -------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"` | +| `data[].id` | string | | The id of the workspace to add the variable set to | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully added variable set to the requested workspaces | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-YwfuBJZkdai4xj9w" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv/relationships/workspaces +``` + +## Remove a Variable Set from Workspaces + +Accepts a list of workspaces to remove the variable set from. + +`DELETE varsets/:varset_id/relationships/workspaces` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"` | +| `data[].id` | string | | The id of the workspace to delete the variable set from | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully removed variable set from the requested workspaces | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-YwfuBJZkdai4xj9w" + }, + { + "type": "workspaces", + "id": "ws-YwfuBJZkdai4xj9w" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv/relationships/workspaces +``` + +## Apply Variable Set to Projects + +Accepts a list of projects to add the variable set to. When you apply a variable set to a project, all the workspaces in that project will have the variable set applied to them. + +`POST varsets/:varset_id/relationships/projects` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------------------------------ | +| `data[].type` | string | | Must be `"projects"` | +| `data[].id` | string | | The id of the project to add the variable set to | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully added variable set to the requested projects | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "projects", + "id": "prj-YwfuBJZkdai4xj9w" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv/relationships/projects +``` + +## Remove a Variable Set from Projects + +Accepts a list of projects to remove the variable set from. + +`DELETE varsets/:varset_id/relationships/projects` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------- | +| `data[].type` | string | | Must be `"projects"` | +| `data[].id` | string | | The id of the project to delete the variable set from | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully removed variable set from the requested projects | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "projects", + "id": "prj-YwfuBJZkdai4xj9w" + }, + { + "type": "projects", + "id": "prj-lkjasdfiojwerlkj" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv/relationships/projects +``` + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[json api document]: /terraform/enterprise/api-docs#json-api-documents + +[json api error object]: https://jsonapi.org/format/#error-objects + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `vars` | Show each variable in a variable set and all of their attributes including `id`, `key`, `value`, `sensitive`, `category`, `hcl`, `created_at`, and `description`. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/variables.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/variables.mdx new file mode 100644 index 0000000000..987dca3556 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/variables.mdx @@ -0,0 +1,307 @@ +--- +page_title: /vars API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/vars` endpoint to manage + organization-level variables. Learn how to read, create, update, and delete + variables using the API. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Variables API reference + +~> **Important**: The Variables API is **deprecated** and will be removed in a future release. All existing integrations with this API should transition to the [Workspace Variables API](/terraform/enterprise/api-docs/workspace-variables). + +This set of APIs covers create, update, list and delete operations on variables. + +## Create a Variable + +`POST /vars` + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | | The description of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the variable is written once and not visible thereafter. | +| `data.relationships.workspace.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.workspace.data.id` | string | | The ID of the workspace that owns the variable. Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +**Deprecation warning**: The custom `filter` properties are replaced by JSON API `relationships` and will be removed from future versions of the API! + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | ----------------------------------------------------- | +| `filter.workspace.name` | string | | The name of the workspace that owns the variable. | +| `filter.organization.name` | string | | The name of the organization that owns the workspace. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "category":"terraform", + "hcl":false, + "sensitive":false + }, + "relationships": { + "workspace": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/vars +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/vars/var-EavQ1LztoRTQHSNT" + } + } +} +``` + +## List Variables + +`GET /vars` + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ---------------------------- | -------------------------------------------------------------------------- | +| `filter[workspace][name]` | **Required** The name of one workspace to list variables for. | +| `filter[organization][name]` | **Required** The name of the organization that owns the desired workspace. | + +These two parameters are optional but linked; if you include one, you must include both. Without a filter, this method lists variables for all workspaces where you have permission to read variables. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ +"https://app.terraform.io/api/v2/vars?filter%5Borganization%5D%5Bname%5D=my-organization&filter%5Bworkspace%5D%5Bname%5D=my-workspace" +# ?filter[organization][name]=my-organization&filter[workspace][name]=demo01 +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"var-AD4pibb9nxo1468E", + "type":"vars","attributes": { + "key":"name", + "value":"hello", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-cZE9LERN3rGPRAmH", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/vars/var-AD4pibb9nxo1468E" + } + } + ] +} +``` + +## Update Variables + +`PATCH /vars/:variable_id` + +| Parameter | Description | +| -------------- | ------------------------------------- | +| `:variable_id` | The ID of the variable to be updated. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.id` | string | | The ID of the variable to update. | +| `data.attributes` | object | | New attributes for the variable. This object can include `key`, `value`, `description`, `category`, `hcl`, and `sensitive` properties, which are described above under [create a variable](#create-a-variable). All of these properties are optional; if omitted, a property will be left unchanged. | + +### Sample Payload + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "attributes": { + "key":"name", + "value":"mars", + "description": "new description", + "category":"terraform", + "hcl": false, + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/vars/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "description":"new description", + "sensitive":false, + "category":"terraform", + "hcl":false + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/workspace-v2-06/workspaces/workspace-v2-06" + } + } + }, + "links": { + "self":"/api/v2/vars/var-yRmifb4PJj7cLkMG" + } + } +} +``` + +## Delete Variables + +`DELETE /vars/:variable_id` + +| Parameter | Description | +| -------------- | ------------------------------------- | +| `:variable_id` | The ID of the variable to be deleted. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/vars/var-yRmifb4PJj7cLkMG +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/vcs-events.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/vcs-events.mdx new file mode 100644 index 0000000000..7c97d1181d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/vcs-events.mdx @@ -0,0 +1,132 @@ +--- +page_title: /vcs-events API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/vcs-events` endpoint to list VCS-related + events within your organization. +source: terraform-docs-common +--- + +# VCS events API reference + +-> **Note**: The VCS Events API is still in beta as support is being added for additional VCS providers. Currently only GitLab.com connections established after December 2020 are supported. + +VCS (version control system) events describe changes within your organization for VCS-related actions. Events are only stored for 10 days. If information about the [OAuth Client](/terraform/enterprise/api-docs/oauth-clients) or [OAuth Token](/terraform/enterprise/api-docs/oauth-tokens) are available at the time of the event, it will be logged with the event. + +## List VCS events + +This endpoint lists VCS events for an organization + +`GET /organizations/:organization_name/vcs-events` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to list VCS events from. The organization must already exist in the system and the user must have permissions to manage VCS settings. | + +-> **Note:** Viewing VCS events is restricted to the owners team, teams with the "Manage VCS Settings", and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). ([More about permissions](/terraform/enterprise/users-teams-organizations/permissions).) + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | +| `filter[from]` | **Optional.** Must be RFC3339 formatted and in UTC. If omitted, the endpoint will default to 10 days ago. | +| `filter[to]` | **Optional.** Must be RFC3339 formatted and in UTC. If omitted, the endpoint will default to now. | +| `filter[oauth_client_external_ids]` | **Optional.** Format as a comma-separated string. If omitted, the endpoint will return all events. | +| `filter[levels]` | **Optional.** `info` and `error` are the only accepted values. If omitted, the endpoint will return both info and error events. | +| `include` | **Optional.** Allows including related resource data. This endpoint only supports `oauth_client` as a value. Only the `name`, `service-provider`, and `id` will be returned on the OAuth Client object in the `included` block. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z&filter%5Bto%5D=2021-02-12T14%3A09%3A59Z&filter%5Boauth_client_external_ids%5D=oc-hhTM7WNUUgbXJpkW&filter%5Blevels%5D=info&include=oauth_client +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ve-DJpbEwZc98ZedHZG", + "type": "vcs-events", + "attributes": { + "created-at": "2021-02-09 20:07:49.686182 +0000 UTC", + "level": "info", + "message": "Loaded 11 repositories", + "organization-id": "org-SBVreZxVessAmCZG" + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-LePsVhHXhCM6jWf3", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-LePsVhHXhCM6jWf3" + } + }, + "oauth-token": { + "data": { + "id": "ot-Ma2cs8tzjv3LYZHw", + "type": "oauth-tokens" + }, + "links": { + "related": "/api/v2/oauth-tokens/ot-Ma2cs8tzjv3LYZHw" + } + } + } + } + ], + "included": [ + { + "id": "oc-LePsVhHXhCM6jWf3", + "type": "oauth-clients", + "attributes": { + "name": "working", + "service-provider": "gitlab_hosted" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "oauth-tokens": { + "data": [ + { + "id": "ot-Ma2cs8tzjv3LYZHw", + "type": "oauth-tokens" + } + ] + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 8 + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspace-resources.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspace-resources.mdx new file mode 100644 index 0000000000..9f53485fc2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspace-resources.mdx @@ -0,0 +1,126 @@ +--- +page_title: /workspaces/resources API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/workspaces/resources` endpoint to list + all of a workspace's resources. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Workspace resources API reference + +## List Workspace Resources + +`GET /workspaces/:workspace_id/resources` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The ID of the workspace to retrieve resources from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [show workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "resources"`) | Request was successful. | +| [404][] | [JSON API error object][] | Workspace not found or user unauthorized to perform action. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspace resources per page. | + +### Permissions + +To list resources the user must have permission to read resources for the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsr-KNYb3Jj3JTBgoBFs", + "type": "resources", + "attributes": { + "address": "random_pet.animal", + "name": "animal", + "created-at": "2021-10-27", + "updated-at": "2021-10-27", + "module": "root", + "provider": "hashicorp/random", + "provider-type": "random_pet", + "modified-by-state-version-id": "sv-y4pjfGHkGUBAa9AX", + "name-index": null + } + }, + { + "id": "wsr-kYsf5A3hQ1y9zFWq", + "type": "resources", + "attributes": { + "address": "random_pet.animal2", + "name": "animal2", + "created-at": "2021-10-27", + "updated-at": "2021-10-27", + "module": "root", + "provider": "hashicorp/random", + "provider-type": "random_pet", + "modified-by-state-version-id": "sv-y4pjfGHkGUBAa9AX", + "name-index": null + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + ... +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspace-variables.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspace-variables.mdx new file mode 100644 index 0000000000..d3a92c657e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspace-variables.mdx @@ -0,0 +1,298 @@ +--- +page_title: /workspaces/vars API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's workspace `/workspaces/vars` endpoint to + manage workspace-specific variables. Read, create, update, and delete + workspace variables. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Workspace variables API reference + +This set of APIs covers create, update, list and delete operations on workspace variables. + +Viewing variables requires permission to read variables for their workspace. Creating, updating, and deleting variables requires permission to read and write variables for their workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a Variable + +`POST /workspaces/:workspace_id/vars` + +| Parameter | Description | +| --------------- | -------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to create the variable in. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | | The description of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the variable is written once and not visible thereafter. | + +**Deprecation warning**: The custom `filter` properties are replaced by JSON API `relationships` and will be removed from future versions of the API! + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | ----------------------------------------------------- | +| `filter.workspace.name` | string | | The name of the workspace that owns the variable. | +| `filter.organization.name` | string | | The name of the organization that owns the workspace. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "category":"terraform", + "hcl":false, + "sensitive":false + } + } +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false, + "version-id":"1aa07d63ea8ff4df941c94ca9ddfd5d2bd04" + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-EavQ1LztoRTQHSNT" + } + } +} +``` + +## List Variables + +`GET /workspaces/:workspace_id/vars` + +| Parameter | Description | +| --------------- | ---------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list variables for. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ +"https://app.terraform.io/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"var-AD4pibb9nxo1468E", + "type":"vars","attributes": { + "key":"name", + "value":"hello", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false, + "version-id":"1aa07d63ea8ff4df941c94ca9ddfd5d2bd04" + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-cZE9LERN3rGPRAmH", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars/var-AD4pibb9nxo1468E" + } + } + ] +} +``` + +## Update Variables + +`PATCH /workspaces/:workspace_id/vars/:variable_id` + +| Parameter | Description | +| --------------- | ----------------------------------------------- | +| `:workspace_id` | The ID of the workspace that owns the variable. | +| `:variable_id` | The ID of the variable to be updated. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.id` | string | | The ID of the variable to update. | +| `data.attributes` | object | | New attributes for the variable. This object can include `key`, `value`, `description`, `category`, `hcl`, and `sensitive` properties, which are described above under [create a variable](#create-a-variable). All of these properties are optional; if omitted, a property will be left unchanged. | + +### Sample Payload + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "attributes": { + "key":"name", + "value":"mars", + "description":"some description", + "category":"terraform", + "hcl": false, + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false, + "version-id":"1aa07d63ea8ff4df941c94ca9ddfd5d2bd04" + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/workspace-v2-06/workspaces/workspace-v2-06" + } + } + }, + "links": { + "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG" + } + } +} +``` + +## Delete Variables + +`DELETE /workspaces/:workspace_id/vars/:variable_id` + +| Parameter | Description | +| --------------- | ----------------------------------------------- | +| `:workspace_id` | The ID of the workspace that owns the variable. | +| `:variable_id` | The ID of the variable to be deleted. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspaces.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspaces.mdx new file mode 100644 index 0000000000..57e82778fd --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/api-docs/workspaces.mdx @@ -0,0 +1,1686 @@ +--- +page_title: /workspaces API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/workspaces` endpoint to read, create, + update, lock, unlock, and delete workspaces and manage SSH keys, tags, and + remote state consumers. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[speculative plans]: /terraform/enterprise/run/remote-operations#speculative-plans + +# Workspaces API reference + +This topic provides reference information about the workspaces AP. Workspaces represent running infrastructure managed by Terraform. + +## Overview + +The scope of the API includes the following endpoints: + +| Method | Path | Action | +| -------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `POST` | `/organizations/:organization_name/workspaces` | Call this endpoint to [create a workspace](#create-a-workspace). You can apply tags stored as key-value pairs when creating the workspace. | +| `POST` | `/organizations/:organization_name/workspaces/:name/actions/safe-delete` | Call this endpoint to [safely delete a workspace](#safe-delete-a-workspace) by querying the organization and workspace names. | +| `POST` | `/workspaces/:workspace_id/actions/safe-delete` | Call this endpoint [safely delete a workspace](#safe-delete-a-workspace) by querying the workspace ID. | +| `POST` | `/workspaces/:workspace_id/actions/lock` | Call this endpoint to [lock a workspace](#lock-a-workspace). | +| `POST` | `/workspaces/:workspace_id/actions/unlock` | Call this endpoint to [unlock a workspace](#unlock-a-workspace). | +| `POST` | `/workspaces/:workspace_id/actions/force-unlock` | Call this endpoint to [force a workspace to unlock](#force-unlock-a-workspace). | +| `POST` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [add remote state consumers](#get-remote-state-consumers). | +| `POST` | `/workspaces/:workspace_id/relationships/tags` | Call this endpoint to [bind flat string tags to an existing workspace](#add-tags-to-a-workspace). | +| `POST` | `/workspaces/:workspace_id/relationships/data-retention-policy` | Call this endpoint to [show the workspace data retention policy](#show-data-retention-policy). | +| `GET` | `/organizations/:organization_name/workspaces` | Call this endpoint to [list existing workspaces](#list-workspaces). Each project in the response contains a link to `effective-tag-bindings` and `tag-bindings` collections. You can filter the response by tag keys and values using a query string parameter. | +| `GET` | `/organizations/:organization_name/workspaces/:name` | Call this endpoint to [show workspace details](#show-workspace) by querying the organization and workspace names. | +| `GET` | `/workspaces/:workspace_id` | Call this endpoint to [show workspace details](#show-workspace). | +| `GET` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [list remote state consumers](#get-remote-state-consumers). | +| `GET` | `/workspaces/:workspace_id/relationships/tags` | Call this endpoint to [list flat string workspace tags](#get-tags). | +| `GET` | `/workspaces/:workspace_id/tag-bindings` | Call this endpoint to [list workspace key-value tags](#get-tags) bound directly to this workspace. | +| `GET` | `/workspaces/:workspace_id/effective-tag-bindings` | Call this endpoint to [list all workspace key-value tags](#get-tags), including both those bound directly to the workspace as well as those inherited from the parent project. | +| `GET` | `/workspaces/:workspace_id/relationships/data-retention-policy` | Call this endpoint to [show the workspace data retention policy](#show-data-retention-policy). | +| `PATCH` | `/workspaces/:workspace_id/relationships/ssh-key` | Call this endpoint to manage SSH key assignments for workspaces. Refer to [Assign an SSH key to a workspace](#assign-an-ssh-key-to-a-workspace) and [Unassign an SSH key from a workspace](#unassign-an-ssh-key-from-a-workspace) for instructions. | +| `PATCH` | `/workspaces/:workspace_id` | Call this endpoint to [update a workspace](#update-a-workspace). You can apply tags stored as key-value pairs when updating the workspace. | +| `PATCH` | `/organizations/:organization_name/workspaces/:name` | Call this endpoint to [update a workspace](#update-a-workspace) by querying the organization and workspace names. | +| `PATCH` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [replace remote state consumers](#replace-remote-state-consumers). | +| `DELETE` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [delete remote state consumers](#delete-remote-state-consumers). | +| `DELETE` | `/workspaces/:workspace_id/relationships/tags` | Call this endpoint to [delete flat string workspace tags](#remove-tags-from-workspace) from the workspace. | +| `DELETE` | `/workspaces/:workspace_id/relationships/data-retention-policy` | Call this endpoint to [remove a workspace data retention policy](#remove-data-retention-policy). | +| `DELETE` | `/workspaces/:workspace_id` | Call this endpoint to [force delete a workspace](#force-delete-a-workspace), which deletes the workspace without first checking for managed resources. | +| `DELETE` | `/organizations/:organization_name/workspaces/:name` | Call this endpoint to [force delete a workspace](#force-delete-a-workspace), which deletes the workspace without first checking for managed resources, by querying the organization and workspace names. | + +## Requirements + +- You must be a member of a team with the **Read** permission enabled for Terraform runs to view workspaces. +- You must be a member of a team with the **Admin** permissions enabled on the workspace to change settings and force-unlock it. +- You must be a member of a team with the **Lock/unlock** permission enabled to lock and unlock the workspace. +- You must meet one of the following requirements to create a workspace: + - Be the team owner + - Be on a team with the **Manage all workspaces** permission enabled + - Present an [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) when calling the API. + +Refer to [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) for additional information. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a Workspace + +Use the following endpoint to create a new workspace: + +`POST /organizations/:organization_name/workspaces` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to create the workspace in. The organization must already exist in the system, and the user must have permissions to create new workspaces. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +By supplying the necessary attributes under a `vcs-repository` object, you can create a workspace that is configured against a VCS Repository. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"workspaces"`. | +| `data.attributes.name` | string | none | The name of the workspace. Workspace names can only include letters, numbers, `-`, and `_`. The name a unique identifier n the organization. | +| `data.attributes.agent-pool-id` | string | none | Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote` or `local` or if `operations` is set to `true`. | +| `data.attributes.allow-destroy-plan` | boolean | `true` | Whether destroy plans can be queued on the workspace. | +| `data.attributes.assessments-enabled` | boolean | `false` | (previously `drift-detection`) Whether or not HCP Terraform performs health assessments for the workspace. May be overridden by the organization setting `assessments-enforced`. Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in [Remote execution mode](/terraform/enterprise/workspaces/settings#execution-mode). | +| `data.attributes.auto-apply` | boolean | `false` | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, [with some exceptions](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply). | +| `data.attributes.auto-apply-run-trigger` | boolean | `false` | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers. | +| `data.attributes.auto-destroy-at` | string | (nothing) | Timestamp when the next scheduled destroy run will occur, refer to [Scheduled Destroy](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). | +| `data.attributes.auto-destroy-activity-duration` | string | (nothing) | Value and units for [automatically scheduled destroy runs based on workspace activity](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). Valid values are greater than 0 and four digits or less. Valid units are `d` and `h`. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. | +| `data.attributes.description` | string | (nothing) | A description for the workspace. | +| `data.attributes.execution-mode` | string | (nothing) | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use. Valid values are `remote`, `local`, and `agent`. When set to `local`, the workspace will be used for state storage only. This value _must not_ be specified if `operations` is specified, and _must_ be specified if `setting-overwrites.execution-mode` is set to `true`. | +| `data.attributes.file-triggers-enabled` | boolean | `true` | Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either `trigger-prefixes` in conjunction with `working_directory` or `trigger-patterns` to describe the set of changed files that will start a run. If disabled, any push triggers a run. | +| `data.attributes.global-remote-state` | boolean | `false` | Whether the workspace should allow all workspaces in the organization to [access its state data](/terraform/enterprise/workspaces/state) during runs. If `false`, then only specifically approved workspaces can access its state. Manage allowed workspaces using the [Remote State Consumers](/terraform/enterprise/api-docs/workspaces#get-remote-state-consumers) endpoints, documented later on this page. Terraform Enterprise admins can choose the default value for new workspaces if this attribute is omitted. | +| `data.attributes.operations` | boolean | `true` | **DEPRECATED** Use `execution-mode` instead. Whether to use remote execution mode. When set to `false`, the workspace will be used for state storage only. This value must not be specified if `execution-mode` is specified. | +| `data.attributes.queue-all-runs` | boolean | `false` | Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued. | +| `data.attributes.source-name` | string | none | A friendly name for the application or client creating this workspace. If set, this will be displayed on the workspace as "Created via ``". | +| `data.attributes.source-url` | string | none | A URL for the application or client creating this workspace. This can be the URL of a related resource in another app, or a link to documentation or other info about the client. | +| `data.attributes.speculative-enabled` | boolean | `true` | Whether this workspace allows automatic [speculative plans][]. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API. | +| `data.attributes.terraform-version` | string | latest release | Specifies the version of Terraform to use for this workspace. You can specify an exact version or a [version constraint](/terraform/language/expressions/version-constraints) such as `~> 1.0.0`. If you specify a constraint, the workspace always uses the newest release that meets that constraint. If omitted when creating a workspace, this defaults to the latest released version. | +| `data.attributes.trigger-patterns` | array | `[]` | List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository. | +| `data.attributes.trigger-prefixes` | array | `[]` | List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform starts a run when files are changed in any directory path matching the provided set of prefixes. | +| `data.attributes.vcs-repo.branch` | string | repository's default branch | The repository branch that Terraform executes from. If omitted or submitted as an empty string, this defaults to the repository's default branch. | +| `data.attributes.vcs-repo.identifier` | string | none | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | `false` | Whether submodules should be fetched when cloning the VCS repository. | +| `data.attributes.vcs-repo.oauth-token-id` | string | none | Specifies the VCS OAuth connection and token. Call the [`oauth-tokens`](/terraform/enterprise/api-docs/oauth-tokens) endpoint to retrieve the OAuth ID. | +| `data.attributes.vcs-repo.tags-regex` | string | none | A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. | +| `data.attributes.vcs-repo` | object | none | Settings for the workspace's VCS repository. If omitted, the workspace is created without a VCS repo. If included, you must specify at least the `oauth-token-id` and `identifier` keys. | +| `data.attributes.working-directory` | string | (nothing) | A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository. | +| `data.attributes.setting-overwrites` | object | none | The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is `true` by default. To overwrite the default inherited value, set an attribute's value to `false`. For example, to set `execution-mode` as the organization default, set `setting-overwrites.execution-mode` to `false`. | +| `data.relationships` | object | none | Specifies a group of workspace associations. | +| `data.relationships.project.data.id` | string | default project | The ID of the project to create the workspace in. If left blank, Terraform creates the workspace in the organization's default project. You must have permission to create workspaces in the project, either by organization-level permissions or team admin access to a specific project. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to attach to the workspace. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +_Without a VCS repository_ + +```json +{ + "data": { + "attributes": { + "name": "workspace-1" + }, + "type": "workspaces" + } +} +``` + +_With Key/Value Tags_ + +```json +{ + "data": { + "attributes": { + "name": "workspace-1" + }, + "type": "workspaces", + "relationships": { + "tag-bindings": { + { + "data": [{ + "type": "tag-bindings", + "attributes": { "key": "env", "value": "test"} + }] + } + } + } + } +} +``` + +_With a VCS repository_ + +```json +{ + "data": { + "attributes": { + "name": "workspace-2", + "terraform_version": "0.11.1", + "working-directory": "", + "vcs-repo": { + "identifier": "example/terraform-test-proj", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "", + "tags-regex": null + } + }, + "type": "workspaces" + } +} +``` + +_Using Git Tags_ + +HCP Terraform triggers a run when you push a Git tag that matches the regular expression (SemVer): `1.2.3`, `22.33.44`, etc. + +```json +{ + "data": { + "attributes": { + "name": "workspace-3", + "terraform_version": "0.12.1", + "file-triggers-enabled": false, + "working-directory": "/networking", + "vcs-repo": { + "identifier": "example/terraform-test-proj-monorepo", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "", + "tags-regex": "\d+.\d+.\d+" + } + }, + "type": "workspaces" + } +} +``` + +_For a monorepo using trigger prefixes_ + +A run will be triggered in this workspace when changes are detected in any of the specified directories: `/networking`, `/modules`, or `/vendor`. + +```json +{ + "data": { + "attributes": { + "name": "workspace-3", + "terraform_version": "0.12.1", + "file-triggers-enabled": true, + "trigger-prefixes": ["/modules", "/vendor"], + "working-directory": "/networking", + "vcs-repo": { + "identifier": "example/terraform-test-proj-monorepo", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "" + }, + "updated-at": "2017-11-29T19:18:09.976Z" + }, + "type": "workspaces" + } +} +``` + +_For a monorepo using trigger patterns_ + +A run will be triggered in this workspace when HCP Terraform detects any of the following changes: + +- A file with the extension `tf` in any directory structure in which the last folder is named `networking` (e.g., `root/networking` and `root/module/networking`) +- Any file changed in the folder `/base`, no subfolders are included +- Any file changed in the folder `/submodule` and all of its subfolders + +```json +{ + "data": { + "attributes": { + "name": "workspace-4", + "terraform_version": "1.2.2", + "file-triggers-enabled": true, + "trigger-patterns": ["/**/networking/*.tf", "/base/*", "/submodule/**/*"], + "vcs-repo": { + "identifier": "example/terraform-test-proj-monorepo", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "" + }, + "updated-at": "2022-06-09T19:18:09.976Z" + }, + "type": "workspaces" + } +} +``` + +_Using HCP Terraform agents_ + +[HCP Terraform agents](/terraform/enterprise/api-docs/agents) allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. + +```json +{ + "data": { + "attributes": { + "name":"workspace-1", + "execution-mode": "agent", + "agent-pool-id": "apool-ZjT6A7mVFm5WHT5a" + } + }, + "type": "workspaces" +} +``` + +_Using an organization default execution mode_ + +```json +{ + "data": { + "attributes": { + "name":"workspace-with-default", + "setting-overwrites": { + "execution-mode": false + } + } + }, + "type": "workspaces" +} + +``` + +_With a project_ + +```json +{ + "data": { + "type": "workspaces", + "attributes": { + "name": "workspace-in-project" + }, + "relationships": { + "project": { + "data": { + "type": "projects", + "id": "prj-jT92VLSFpv8FwKtc" + } + } + } + } +} +``` + +_With key-value tags_ + +```json +{ + "data": { + "type": "workspaces", + "attributes": { + "name": "workspace-in-project" + } + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces +``` + +### Sample Response + +_Without a VCS repository_ + +**Note:** The `assessments-enabled` property is only accepted by or returned from HCP Terraform. + +@include 'api-code-blocks/workspace.mdx' + +_With a VCS repository_ + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +_With a project_ + +```json +{ + "data": { + "id": "ws-HRkJLSYWF97jucqQ", + "type": "workspaces", + "attributes": { + "allow-destroy-plan": true, + "auto-apply": false, + "auto-apply-run-trigger": false, + "auto-destroy-at": null, + "auto-destroy-activity-duration": null, + "created-at": "2022-12-05T20:57:13.829Z", + "environment": "default", + "locked": false, + "locked-reason": "", + "name": "workspace-in-project", + "queue-all-runs": false, + "speculative-enabled": true, + "structured-run-output-enabled": true, + "terraform-version": "1.3.5", + "working-directory": null, + "global-remote-state": true, + "updated-at": "2022-12-05T20:57:13.829Z", + "resource-count": 0, + "apply-duration-average": null, + "plan-duration-average": null, + "policy-check-failures": null, + "run-failures": null, + "workspace-kpis-runs-count": null, + "latest-change-at": "2022-12-05T20:57:13.829Z", + "operations": true, + "execution-mode": "remote", + "vcs-repo": null, + "vcs-repo-identifier": null, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-queue-run": true, + "can-read-variable": true, + "can-update-variable": true, + "can-read-state-versions": true, + "can-read-state-outputs": true, + "can-create-state-versions": true, + "can-queue-apply": true, + "can-lock": true, + "can-unlock": true, + "can-force-unlock": true, + "can-read-settings": true, + "can-manage-tags": true, + "can-manage-run-tasks": false, + "can-force-delete": true, + "can-manage-assessments": true, + "can-read-assessment-results": true, + "can-queue-destroy": true + }, + "actions": { + "is-destroyable": true + }, + "description": null, + "file-triggers-enabled": true, + "trigger-prefixes": [], + "trigger-patterns": [], + "assessments-enabled": false, + "last-assessment-result-at": null, + "source": "tfe-api", + "source-name": null, + "source-url": null, + "tag-names": [], + "setting-overwrites": { + "execution-mode": false, + "agent-pool": false + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "current-run": { + "data": null + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/effective-tag-bindings" + } + }, + "latest-run": { + "data": null + }, + "outputs": { + "data": [] + }, + "remote-state-consumers": { + "links": { + "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/relationships/remote-state-consumers" + } + }, + "current-state-version": { + "data": null + }, + "current-configuration-version": { + "data": null + }, + "agent-pool": { + "data": null + }, + "readme": { + "data": null + }, + "project": { + "data": { + "id": "prj-jT92VLSFpv8FwKtc", + "type": "projects" + } + }, + "current-assessment-result": { + "data": null + }, + "tag-bindings": { + "links": { + "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/tag-bindings" + } + }, + "vars": { + "data": [] + }, + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/workspace-in-project" + } + } +} +``` + +## Update a Workspace + +Use one of the following endpoint to update a workspace: + +- `PATCH /organizations/:organization_name/workspaces/:name` +- `PATCH /workspaces/:workspace_id` + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to update | +| `:organization_name` | The name of the organization the workspace belongs to. | +| `:name` | The name of the workspace to update. Workspace names are unique identifiers in the organization and can only include letters, numbers, `-`, and `_`. | + +### Request Body + +These PATCH endpoints require a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.attributes.name` | string | (previous value) | A new name for the workspace, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. **Warning:** Changing a workspace's name changes its URL in the API and UI. | +| `data.attributes.agent-pool-id` | string | (previous value) | Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote` or `local` or if `operations` is set to `true`. | +| `data.attributes.allow-destroy-plan` | boolean | (previous value) | Whether destroy plans can be queued on the workspace. | +| `data.attributes.assessments-enabled` | boolean | `false` | (previously `drift-detection`) Whether or not HCP Terraform performs health assessments for the workspace. May be overridden by the organization setting `assessments-enforced`. Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in [Remote execution mode](/terraform/enterprise/workspaces/settings#execution-mode). | +| `data.attributes.auto-apply` | boolean | (previous value) | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, [with some exceptions](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply). | +| `data.attributes.auto-apply-run-trigger` | boolean | (previous value) | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers. | +| `data.attributes.auto-destroy-at` | string | (previous value) | Timestamp when the next scheduled destroy run will occur, refer to [Scheduled Destroy](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). | +| `data.attributes.auto-destroy-activity-duration` | string | (previous value) | Value and units for [automatically scheduled destroy runs based on workspace activity](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). Valid values are greater than 0 and four digits or less. Valid units are `d` and `h`. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. | +| `data.attributes.description` | string | (previous value) | A description for the workspace. | +| `data.attributes.execution-mode` | string | (previous value) | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use. Valid values are `remote`, `local`, and `agent`. When set to `local`, the workspace will be used for state storage only. This value _must not_ be specified if `operations` is specified, and _must_ be specified if `setting-overwrites.execution-mode` is set to `true`. | +| `data.attributes.file-triggers-enabled` | boolean | (previous value) | Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either `trigger-prefixes` in conjunction with `working_directory` or `trigger-patterns` to describe the set of changed files that will start a run. If disabled, any push will trigger a run. | +| `data.attributes.global-remote-state` | boolean | (previous value) | Whether the workspace should allow all workspaces in the organization to [access its state data](/terraform/enterprise/workspaces/state) during runs. If `false`, then only specifically approved workspaces can access its state. Manage allowed workspaces using the [Remote State Consumers](/terraform/enterprise/api-docs/workspaces#get-remote-state-consumers) endpoints, documented later on this page. | +| `data.attributes.operations` | boolean | (previous value) | **DEPRECATED** Use `execution-mode` instead. Whether to use remote execution mode. When set to `false`, the workspace will be used for state storage only. This value must not be specified if `execution-mode` is specified. | +| `data.attributes.queue-all-runs` | boolean | (previous value) | Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued. | +| `data.attributes.speculative-enabled` | boolean | (previous value) | Whether this workspace allows automatic [speculative plans][]. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API. | +| `data.attributes.terraform-version` | string | (previous value) | The version of Terraform to use for this workspace. This can be either an exact version or a [version constraint](/terraform/language/expressions/version-constraints) (like `~> 1.0.0`); if you specify a constraint, the workspace will always use the newest release that meets that constraint. | +| `data.attributes.trigger-patterns` | array | (previous value) | List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository. | +| `data.attributes.trigger-prefixes` | array | (previous value) | List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform will start a run when files are changed in any directory path matching the provided set of prefixes. | +| `data.attributes.vcs-repo.branch` | string | (previous value) | The repository branch that Terraform will execute from. | +| `data.attributes.vcs-repo.identifier` | string | (previous value) | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | (previous value) | Whether submodules should be fetched when cloning the VCS repository. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The VCS Connection (OAuth Connection + Token) to use as identified. Get this ID from the [oauth-tokens](/terraform/enterprise/api-docs/oauth-tokens) endpoint. You can not specify this value if `github-app-installation-id` is specified. | +| `data.attributes.vcs-repo.github-app-installation-id` | string | | The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from **Account Settings** within HCP Terraform. You can not specify this value if `oauth-token-id` is specified. | +| `data.attributes.vcs-repo.tags-regex` | string | (previous value) | A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. | +| `data.attributes.vcs-repo` | object or null | (previous value) | To delete a workspace's existing VCS repo, specify `null` instead of an object. To modify a workspace's existing VCS repo, include whichever of the keys below you wish to modify. To add a new VCS repo to a workspace that didn't previously have one, include at least the `oauth-token-id` and `identifier` keys. | +| `data.attributes.working-directory` | string | (previous value) | A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository. | +| `data.attributes.setting-overwrites` | object | | The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is `true` by default. To overwrite the default inherited value, set an attribute's value to `false`. For example, to set `execution-mode` as the organization default, you set `setting-overwrites.execution-mode = false`. | +| `data.relationships` | object | none | Specifies a group of workspace relationships. | +| `data.relationships.project.data.id` | string | existing value | The ID of the project to move the workspace to. If left blank or unchanged, the workspace will not be moved. You must have admin permissions on both the source project and destination project in order to move a workspace between projects. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to attach to the workspace. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "workspace-2", + "resource-count": 0, + "terraform_version": "0.11.1", + "working-directory": "", + "vcs-repo": { + "identifier": "example/terraform-test-proj", + "branch": "", + "ingress-submodules": false, + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ" + }, + "updated-at": "2017-11-29T19:18:09.976Z" + }, + "relationships": { + "project": { + "data": { + "type": "projects", + "id": "prj-7HWWPGY3fYxztELU" + } + }, + "tag-bindings": { + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "environment", + "value": "development" + } + }, + ] + } + }, + "type": "workspaces" + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-2 +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## List workspaces + +This endpoint lists workspaces in the organization. + +`GET /organizations/:organization_name/workspaces` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------- | +| `:organization_name` | The name of the organization to list the workspaces of. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | +| `search[name]` | **Optional.** If specified, restricts results to workspaces with a name that matches the search string using a fuzzy search. | +| `search[tags]` | **Optional.** If specified, restricts results to workspaces with that tag. If multiple comma separated values are specified, results matching all of the tags are returned. | +| `search[exclude-tags]` | **Optional.** If specified, results exclude workspaces with that tag. If multiple comma separated values are specified, workspaces with tags matching any of the tags are excluded. | +| `search[wildcard-name]` | **Optional.** If specified, restricts results to workspaces with partial matching, using `*` on prefix, suffix, or both. For example, `search[wildcard-name]=*-prod` returns all workspaces ending in `-prod`, `search[wildcard-name]=prod-*` returns all workspaces beginning with `prod-`, and `search[wildcard-name]=*-prod-*` returns all workspaces with substring `-prod-` regardless of prefix and/or suffix. | +| `sort` | **Optional.** Allows sorting the organization's workspaces by a provided value. You can sort by `"name"`, `"current-run.created-at"` (the time of the current run), and `"latest-change-at"` (the creation time of the latest state version or the workspace itself if no state version exists). Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable. | +| `filter[project][id]` | **Optional.** If specified, restricts results to workspaces in the specific project. | +| `filter[current-run][status]` | **Optional.** If specified, restricts results to workspaces that match the status of a current run. | +| `filter[tagged][i][key]` | **Optional.** If specified, restricts results to workspaces that are tagged with the provided key. Use a value of "0" for `i` if you are only using a single filter. For multiple tag filters, use an incrementing integer value for each filter. Multiple tag filters will be combined together with a logical AND when filtering results. | +| `filter[tagged][i][value]` | **Optional.** If specified, restricts results to workspaces that are tagged with the provided value. This is useful when combined with a `key` filter for more specificity. Use a value of "0" for `i` if you are only using a single filter. For multiple tag filters, use an incrementing integer value for each filter. Multiple tag filters will be combined together with a logical AND when filtering results. | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces +``` + +_With multiple tag filters_ + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces?filter%5B%tagged5D%5B0%5D%5Bkey%5D=environment&filter%5B%tagged5D%5B0%5D%5Bvalue%5D=development&filter%5B%tagged5D%5B1%5D%5Bkey%5D=meets-compliance +``` + +### Sample Response + +@include 'api-code-blocks/workspaces-list.mdx' + +## Show workspace + +Details on a workspace can be retrieved from two endpoints, which behave identically. + +One refers to a workspace by its ID: + +`GET /workspaces/:workspace_id` + +| Parameter | Description | +| --------------- | ---------------- | +| `:workspace_id` | The workspace ID | + +The other refers to a workspace by its name and organization: + +`GET /organizations/:organization_name/workspaces/:name` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the workspace belongs to. | +| `:name` | The name of the workspace to show details for, which can only include letters, numbers, `-`, and `_`. | + +### Workspace performance attributes + +The following attributes are helpful in determining the overall health and performance of your workspace configuration. These metrics refer to the **past 30 runs that have either resulted in an error or successfully applied**. + +| Parameter | Type | Description | +| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------- | +| `data.attributes.apply-duration-average` | number | This is the average time runs spend in the **apply** phase, represented in milliseconds | +| `data.attributes.plan-duration-average` | number | This is the average time runs spend in the **plan** phase, represented in milliseconds | +| `data.attributes.policy-check-failures` | number | Reports the number of run failures resulting from a policy check failure | +| `data.attributes.run-failures` | number | Reports the number of failed runs | +| `data.attributes.workspace-kpis-run-count` | number | Total number of runs taken into account by these metrics | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1 +``` + +### Sample Response + +@include 'api-code-blocks/workspace.mdx' + +## Safe Delete a workspace + +When you delete an HCP Terraform workspace with resources, Terraform can no longer track or manage that infrastructure. During a safe delete, HCP Terraform only deletes the workspace if it is not managing resources. + +You can safe delete a workspace using two endpoints that behave identically. The first endpoint identifies a workspace with the workspace ID, and the other identifies the workspace by its name and organization. + +`POST /workspaces/:workspace_id/actions/safe-delete` + +| Parameter | Description | +| --------------- | ---------------------------------- | +| `:workspace_id` | The ID of the workspace to delete. | + +`POST /organizations/:organization_name/workspaces/:name/actions/safe-delete` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the workspace's organization. | +| `:name` | The name of the workspace to delete, which can only include letters, numbers, `-`, and `_`. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform workspace delete | +| [409][] | [JSON API error object][] | Workspace is not safe to delete because it is managing resources | + +## Force Delete a workspace + +During a force delete, HCP Terraform removes the specified workspace without checking whether it is managing resources. We recommend using the [safe delete endpoint](#safe-delete-a-workspace) instead, when possible. + +!> **Warning:** Terraform cannot track or manage the workspace's infrastructure after deletion. We recommend [destroying the workspace's infrastructure](/terraform/enterprise/run/modes-and-options#destroy-mode) before you delete it. + +By default, only organization owners can force delete workspaces. Organization owners can also update [organization's settings]\(/terraform/cloud-docs/users-teams organizations/organizations#general) to let workspace admins force delete their own workspaces. + +You can use two endpoints to force delete a workspace, which behave identically. One endpoint identifies the workspace with its workspace ID and the other endpoint identifies the workspace with its name and organization. + +`DELETE /workspaces/:workspace_id` + +| Parameter | Description | +| --------------- | --------------------------------- | +| `:workspace_id` | The ID of the workspace to delete | + +`DELETE /organizations/:organization_name/workspaces/:name` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the workspace belongs to. | +| `:name` | The name of the workspace to delete, which can only include letters, numbers, `-`, and `_`. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the workspace | +| [403][] | [JSON API error object][] | Not authorized to perform a force delete on the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform workspace delete | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1 +``` + +## Lock a workspace + +This endpoint locks a workspace. + +`POST /workspaces/:workspace_id/actions/lock` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to lock. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | -------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully locked the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [409][] | [JSON API error object][] | Workspace already locked | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | ------ | ------- | ------------------------------------- | +| `reason` | string | `""` | The reason for locking the workspace. | + +### Sample Payload + +```json +{ + "reason": "Locking workspace-1" +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/lock +``` + +### Sample Response + +@include 'api-code-blocks/workspace.mdx' + +## Unlock a workspace + +This endpoint unlocks a workspace. Unlocking a workspace sets the current state version to the latest finalized intermediate state version. If intermediate state versions are available, but HCP Terraform has not yet finalized the latest intermediate state version, the unlock will fail with a 503 response. For this particular error, it's recommended to retry the unlock operation for a short period of time until the platform finalizes the state version. If you must force-unlock a workspace under these conditions, ensure that state was saved successfully by inspecting the latest state version using the [State Version List API](/terraform/enterprise/api-docs/state-versions#list-state-versions-for-a-workspace) + +`POST /workspaces/:workspace_id/actions/unlock` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to unlock. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | -------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully unlocked the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [409][] | [JSON API error object][] | Workspace already unlocked, or locked by a different user | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/unlock +``` + +### Sample Response + +@include 'api-code-blocks/workspace.mdx' + +## Force Unlock a workspace + +This endpoint force unlocks a workspace. Only users with admin access are authorized to force unlock a workspace. + +`POST /workspaces/:workspace_id/actions/force-unlock` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to force unlock. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | -------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully force unlocked the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [409][] | [JSON API error object][] | Workspace already unlocked | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/force-unlock +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## Assign an SSH key to a workspace + +This endpoint assigns an SSH key to a workspace. + +`PATCH /workspaces/:workspace_id/relationships/ssh-key` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to assign the SSH key to. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.attributes.id` | string | | The SSH key ID to assign. Obtain this from the [ssh-keys](/terraform/enterprise/api-docs/ssh-keys) endpoint. | + +#### Sample Payload + +```json +{ + "data": { + "attributes": { + "id": "sshkey-GxrePWre1Ezug7aM" + }, + "type": "workspaces" + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## Unassign an SSH key from a workspace + +This endpoint unassigns the currently assigned SSH key from a workspace. + +`PATCH /workspaces/:workspace_id/relationships/ssh-key` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to assign the SSH key to. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------- | ------ | ------- | ----------------------- | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.attributes.id` | string | | Must be `null`. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "id": null + }, + "type": "workspaces" + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## Get Remote State Consumers + +`GET /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to get remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint retrieves the list of other workspaces that are allowed to access the given workspace's state during runs. + +- If `global-remote-state` is set to false for the workspace, this will return the list of other workspaces that are specifically authorized to access the workspace's state. +- If `global-remote-state` is set to true, this will return a list of every workspace in the organization except for the subject workspace. + +The list returned by this endpoint is subject to the caller's normal workspace permissions; it will not include workspaces that the provided API token is unable to read. + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/remote-state-consumers +``` + +### Sample Response + +@include 'api-code-blocks/workspaces-list.mdx' + +## Replace Remote State Consumers + +`PATCH /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to replace remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint updates the workspace's remote state consumers to be _exactly_ the list of workspaces specified in the payload. It can only be used for workspaces where `global-remote-state` is false. + +This endpoint can only be used by teams with permission to manage workspaces for the entire organization — only those who can _view_ the entire list of consumers can _replace_ the entire list. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) Teams with admin permissions on specific workspaces can still modify remote state consumers for those workspaces, but must use the add (POST) and remove (DELETE) endpoints listed below instead of this PATCH endpoint. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully updated remote state consumers | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"`. | +| `data[].id` | string | | The ID of a workspace to be set as a remote state consumer. | + +### Sample Payload + +```json +{ + "data": [ + { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers +``` + +### Response + +No response body. + +Status code `204`. + +## Add Remote State Consumers + +`POST /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to add remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint adds one or more remote state consumers to the workspace. It can only be used for workspaces where `global-remote-state` is false. + +- The workspaces specified as consumers must be readable to the API token that makes the request. +- A workspace cannot be added as a consumer of itself. (A workspace can always read its own state, regardless of access settings.) +- You can safely add a consumer workspace that is already present; it will be ignored, and the rest of the consumers in the request will be processed normally. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully updated remote state consumers | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"`. | +| `data[].id` | string | | The ID of a workspace to be set as a remote state consumer. | + +### Sample Payload + +```json +{ + "data": [ + { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers +``` + +### Response + +No response body. + +Status code `204`. + +## Delete Remote State Consumers + +`DELETE /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to remove remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint removes one or more remote state consumers from a workspace, according to the contents of the payload. It can only be used for workspaces where `global-remote-state` is false. + +- The workspaces specified as consumers must be readable to the API token that makes the request. +- You can safely remove a consumer workspace that is already absent; it will be ignored, and the rest of the consumers in the request will be processed normally. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully updated remote state consumers | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ---------------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"`. | +| `data[].id` | string | | The ID of a workspace to remove from the remote state consumers. | + +### Sample Payload + +```json +{ + "data": [ + { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers +``` + +### Response + +No response body. + +Status code `204`. + +## List workspace tags + +Workspace tags are [organization tags](/terraform/enterprise/api-docs/organization-tags) added to a workspace. They are a flat list of keys that can only be applied to workspaces when using the `tags` attribute in the Terraform `cloud` block in Terraform v1.9 and older. To list key-value tags supported in Terraform v1.10 and newer, refer to [List workspace tag bindings](#list-workspace-tag-bindings). + +`GET /workspaces/:workspace_id/relationships/tags`: Paginated list of flat string tags attached to the workspace. + +### Path parameters + +| Parameter | Description | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to fetch tags for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Query Parameters + +Only the flat string tags endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. Conversely, all tags are returned when using fetching tag-bindings or effective-tag-bindings endpoints. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | + +### Sample Requests + + + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/relationships/tags +``` + + + +### Sample Responses + + + +```json +{ + "data": [ + { + "id": "tag-1", + "type": "tags", + "attributes": { + "name": "tag1", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 1 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "tag-2", + "type": "tags", + "attributes": { + "name": "tag2", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ] +} +``` + + + +## List workspace tag bindings + +Call the following endpoints to list the tags attached to a workspace: + +- `GET /workspaces/:workspace_id/tag-bindings`: Lists key-value tags directly bound to the workspace. +- `GET /workspaces/:workspace_id/effective-tag-bindings`: Lists all key-value tags bound to the workspace, including those inherited from the parent project. + +### Path parameters + +| Parameter | Description | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to fetch tags for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Sample Requests + + + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/tag-bindings +``` + + + + + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/effective-tag-bindings +``` + + + +### Sample Responses + + + +```json +{ + "data": [ + { + "id": "tb-232e23631380f79e", + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123", + "created-at": "2024-11-19T23:59:24.648Z" + } + } + ], + "links": { + "target": "/api/v2/workspaces/ws-db61c9eb5cab5ae2" + } +} +``` + + +
+ + +```json +{ + "data": [ + { + "id": "07cc44202a430fc2", + "type": "effective-tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "id": "f8b11951f98e11f8", + "type": "effective-tag-bindings", + "attributes": { + "key": "dept", + "value": "r+d" + }, + "relationships": { + "inherited-from": { + "links": { + "related": "/api/v2/projects/prj-af7d174fa1ea7423" + } + } + } + } + ] +} +``` + + + +## Add flat string tags to a workspace + +`POST /workspaces/:workspace_id/relationships/tags` + +To add key-value tags to an existing workspace, call the `PATCH /workspaces/:workspace_id` and provide workspace tag bindings in the JSON payload. Refer to [Update a workspace](#update-a-workspace) for additional information. + +You can also bind key-value tags when creating a workspace. Refer to [Create a workspace](#create-a-workspace) for additional information. + +Refer to [Define project tags](/terraform/enterprise/projects/manage#define-project-tags) for information about supported tag values. + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The workspace ID to add tags to. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Successfully added tags to workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that `type`, as well as one of `id` _or_ `attributes.name` is required. + +| Key path | Type | Default | Description | +| ------------------------ | ------ | ------- | --------------------------- | +| `data[].type` | string | | Must be `"tags"`. | +| `data[].id` | string | | The ID of the tag to add. | +| `data[].attributes.name` | string | | The name of the tag to add. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tags", + "attributes": { + "name": "foo" + } + }, + { + "type": "tags", + "attributes": { + "name": "bar" + } + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/workspace-2/relationships/tags +``` + +### Sample Response + +No response body. + +Status code `204`. + +## Remove tags from workspace + +This endpoint removes one or more tags from a workspace. The workspace must already exist, and tag +element that supplies an `id` attribute must exist. If the `name` attribute is used, and no matching +organization tag is found, no action will occur for that entry. Tags removed from all workspaces will be +removed from the organization-wide list. + +To remove key-value tags to an existing workspace, call the `PATCH /workspaces/:workspace_id` and provide workspace tag bindings in the JSON payload. Refer to [Update a workspace](#update-a-workspace) for additional information. + +`DELETE /workspaces/:workspace_id/relationships/tags` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to remove tags from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Successfully removed tags to workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that `type`, as well as one of `id` _or_ `attributes.name` is required. + +| Key path | Type | Default | Description | +| ------------------------ | ------ | ------- | ------------------------------ | +| `data[].type` | string | | Must be `"tags"`. | +| `data[].id` | string | | The ID of the tag to remove. | +| `data[].attributes.name` | string | | The name of the tag to remove. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tags", + "id": "tag-Yfha4YpPievQ8wJw" + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/workspace-2/relationships/tags +``` + +### Sample Response + +No response body. + +Status code `204`. + +## Add/update tag-bindings on a workspace + +This endpoint adds keys and values or updates values of tag-bindings on an existing resource by key. +It does not remove any keys from the collection. This endpoint is useful when you want to ensure a +modification is additive. + +Tag Bindings have special constraints: + +- Up to 10 tags can be applied to a workspace, but an additional 10 tags may be inherited from its project. +- Keys must be no more than 128 characters, allowing all alphanumeric characters plus the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. +- Values allow the same characters, but can be up to 256 characters. +- Certain key prefixes, including `hc:` and `hcp:` are not allowed. + +`PATCH /workspaces/:workspace_id/tag-bindings` + +| Parameter | Description | +| --------------- | --------------------------------- | +| `:workspace_id` | The ID of the workspace to update | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that for each data item, `type`, as well as `attributes.key` is required. + +| Key path | Type | Default | Description | +| ------------------------- | ------ | ------- | ---------------------------------- | +| `data[].type` | string | | Must be `"tag-bindings"`. | +| `data[].attributes.key` | string | | The key of the tag to add/update. | +| `data[].attributes.value` | string | | The name of the tag to add/update. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-82d2281aa259ba09/tag-bindings +``` + +### Sample Response + +Status Code 200 + + + +```json +{ + "data": [ + { + "id": "tb-e4a5847b2cf06559", + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "id": "tb-97ce954636f93a6c", + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + + + +## Show data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`GET /workspaces/:workspace_id/relationships/data-retention-policy` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to show the data retention policy for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or by sending a `GET` request to the [`/workspaces`](#show-workspace) endpoint. | + +This endpoint shows the data retention policy set explicitly on the workspace. +When no data retention policy is set for the workspace, the endpoint returns the default policy configured for the organization. Refer to [Data Retention Policies](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) for instructions on configuring data retention policies for workspaces. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#show-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Create or update data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`POST /workspaces/:workspace_id/relationships/data-retention-policy` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The workspace ID to update the data retention policy for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or by sending a `GET` request to the [`/workspaces`](#show-workspace) endpoint. | + +This endpoint creates a data retention policy for a workspace or updates the existing policy. +Refer to [Data Retention Policies](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) for additional information. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#create-or-update-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Remove data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`DELETE /workspaces/:workspace_id/relationships/data-retention-policy` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to remove the data retenetion policy for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or by sending a `GET` request to the [`/workspaces`](#show-workspace) endpoint. | + +This endpoint removes the data retention policy explicitly set on a workspace. +When no data retention policy is set for the workspace, the endpoint returns the default policy configured for the organization. Refer to [Data Retention Policies](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) for instructions on configuring data retention policies for organizations. + +Read more about [workspace data retention policies](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies). + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#remove-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `current_configuration_version` - The last configuration this workspace received, excluding plan-only configurations. Terraform uses this configuration for new runs, unless you provide a different one. +- `current_configuration_version.ingress_attributes` - The commit information for the current configuration version. +- `current_run` - Additional information about the current run. +- `current_run.configuration_version` - The configuration used in the current run. +- `current_run.configuration_version.ingress_attributes` - The commit information used in the current run. +- `current_run.plan` - The plan used in the current run. +- `locked_by` - The user, team, or run responsible for locking the workspace, if the workspace is currently locked. +- `organization` - The full organization record. +- `outputs` - The outputs for the most recently applied run. +- `project` - The full project record. +- `readme` - The most recent workspace README.md. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/admin-access.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/admin-access.mdx new file mode 100644 index 0000000000..82283fbba8 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/admin-access.mdx @@ -0,0 +1,29 @@ +--- +page_title: Access Terraform Enterprise administration settings +description: >- + The admin interface provides access to general settings, system-wide integration settings, and accounts and resources. Learn how to access the administration settings. +--- + +# Access Administration Settings + +This topic describes how to access the Terraform Enterprise administration interface. The interface provies access to general settings, system-wide integration settings, and accounts and resources. + +## Introduction + +In Terraform Enterprise instances, the HCP Terraform application includes an admin interface for managing general settings, systemwide integration settings, and accounts and resources. + +Administration functions can be managed via user interface (as described by the pages in this section) or via the [Admin API](/terraform/enterprise/api-docs/admin). Only Terraform Enterprise users with the site-admin permission can access the administrative functions. + +The initial user account for a Terraform Enterprise instance is the first site admin. Site admins can grant admin permissions to other users in the "Users" section of the admin pages. See [Promoting a User to Administrator](/terraform/enterprise/application-administration/resources#promoting-a-user-to-administrator) for details. + +To navigate to the site admin section of the UI, click your user icon, then click **Admin**: + +The admin area defaults to showing the user management page. Use the navigation to access the other administrative functions. + +## Administration Tasks + +- [General settings](/terraform/enterprise/application-administration/general) +- [Service Integrations](/terraform/enterprise/application-administration/integration) +- [Managing Accounts and Resources](/terraform/enterprise/application-administration/resources) +- [Managing OPA tool versions](/terraform/enterprise/application-administration/opa-tool-versions) +- [Managing Sentinel tool versions](/terraform/enterprise/application-administration/sentinel-tool-versions) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/agents-on-tfe.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/agents-on-tfe.mdx new file mode 100644 index 0000000000..b7bf816c0f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/agents-on-tfe.mdx @@ -0,0 +1,53 @@ +--- +page_title: HCP Terraform agents for Terraform Enterprise +description: HCP Terraform agents let Terraform manage isolated, private, or on-premises + infrastructure. Learn about HCP Terraform agent behavior for Terraform Enterprise. +--- + +# HCP Terraform agents for Terraform Enterprise + +This topic describes HCP Terraform agent behavior when connected to Terraform Enterprise. + +## Introduction + +HCP Terraform agents allow Terraform Enterprise to communicate with isolated, +private, or on-premises infrastructure. By deploying lightweight agents within a +specific network segment, you can establish a simple connection between your +environment and Terraform Enterprise which allows for provisioning operations and +management. + +Refer to [HCP Terraform agents](/terraform/cloud-docs/agents) for additional information about HCP Terraform agents + +## Requirements + +Terraform Enterprise v202109-1 or later is required to connect to HCP Terraform agents. + +## Agents on HCP Terraform and Terraform Enterprise + +The following list describes the differences between connecting agents to Terraform Enterprise and connecting to agents on HCP Terraform, which is the software-as-a-service edition of Terraform Enterprise: + +* **No restriction on Agent Count**: Terraform Enterprise does not + place a limitation on the number of Agents that can be registered per organization. + +* **Hostname Registration**: HCP Terraform agents registering with a Terraform Enterprise instance + must define the Terraform Enterprise hostname via the `-address` CLI flag or `TFC_ADDRESS` environment + variable when running `tfc-agent`. By default, `tfc-agent` will attempt to connect to + HCP Terraform, so this value must be explicitly defined when registering with a + Terraform Enterprise instance. + +* **Custom Bundle Support**: HCP Terraform agents on Terraform Enterprise support + [custom Terraform bundles](https://github.com/hashicorp/terraform/tree/main/tools/terraform-bundle). + Custom bundles are created and defined within the Terraform Enterprise application; Agents will + download the custom bundle based on the Terraform version information. See + [using a custom Terraform bundle](https://support.hashicorp.com/hc/en-us/articles/360016992613-Using-custom-and-community-providers-in-Terraform-Cloud-and-Enterprise) + for more detail on custom bundles in Terraform Enterprise. + +* **Network Access Requirements**: HCP Terraform agents on Terraform Enterprise must be able to + communicate with the Terraform Enterprise instance via HTTPS. Additionally, the agent must also be + able to communicate with any services required by the Terraform code it is executing. + This includes the Terraform releases distribution service, [releases.hashicorp.com](https://releases.hashicorp.com), + as well as the [Terraform provider registry](https://registry.terraform.io). Agents + executing in a workspace that leverage a Terraform version that provides a custom + Terraform bundle with pre-existing provider binaries do not need access to these resources. + +* **Agent Version Compatibility**: Terraform Enterprise places restrictions on what versions of HCP Terraform agents can be registered. This is to prevent an incompatible agent from registering with a Terraform Enterprise instance and attempting to execute a Terraform operation in an undefined way. Compatible versions of HCP Terraform agents on Terraform Enterprise will vary based on the specific Terraform Enterprise release sequence; any changes to compatible HCP Terraform agents versions will be noted in the [Terraform Enterprise release notes](/terraform/enterprise/releases). \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/customization.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/customization.mdx new file mode 100644 index 0000000000..37cfdf34cc --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/customization.mdx @@ -0,0 +1,54 @@ +--- +page_title: Customize the UI +description: >- + Use customization settings to modify the Terraform Enterprise user interface. Learn how to change UI text, customize support email addresses, and provide instructions in the UI. +--- + +# Customize the UI + +This topic describes how to customize different parts of the user interface to accommodate the specific needs of your organization. Refer to the [Customization API](/terraform/enterprise/api-docs/admin/settings#list-customization-settings) for instructions about customizing the UI using the API. + +## Access Customization Settings + +To access the customization settings, visit the site admin area and click **Customization**. To save the settings, click **Save Customization Settings**. + +~> **Note:** Terraform Enterprise sanitizes customization content before displaying it, and might remove HTML elements or attributes that pose a possible security risk. + +## Support + +You can update the support content displayed in the UI. + +### Email Address + +Terraform Enterprise uses the support email address for system emails, error pages, and all other situations where users are prompted to contact support. You can specify a local email address if you want users to contact a specific person or team when they have issues. + +Note that this field defaults to `support@hashicorp.com`, which is not a functional email address for HashiCorp support. If you need assistance or want to submit a feature request, visit the [HashiCorp support center](https://support.hashicorp.com/hc/en-us) and open a ticket. + +### Error Instructions + +-> Supports HTML + +Instructions to display when users encounter unexpected errors. You can use this space to provide links to your support triage process or other ticketing systems. + +## Application + +You can customize the following UI elements. + +### Login Help + +-> Supports HTML + +The content provided in this field replaces the "Need an Account? Sign up here." prompt. This is an opportunity to provide system usage disclaimers, or any custom new user processes you may have. + + +### New User Instructions + +-> Supports HTML + +Instructions shown to new users who aren't yet members of an organization. If you have a custom provisioning process for granting organization access, you can explain it here. (By default, new users are prompted to contact the system administrator for organization membership.) + +### Footer Content + +-> Supports HTML + +Content to display in the footer of every application page. Useful for disclaimers and other site-wide communication. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/general.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/general.mdx new file mode 100644 index 0000000000..5291998d44 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/general.mdx @@ -0,0 +1,117 @@ +--- +page_title: Configure general Terraform Enterprise settings +description: >- + Use general settings to control global behavior. Learn how to enable 2FA, limit organization creation, set timeouts, connect agents, and control remote state sharing and speculative plans. +--- + +# Configure General Settings + +This topic describes how to configure general settings in Terraform Enterprise. General settings affect global behaviors, including 2FA, limits on creating organizations, service timeouts, HCP Terraform agent connections, and remote state sharing. Refer to the [Admin Settings API](/terraform/enterprise/api-docs/admin/settings) documentation for instruction on how to configure general settings using the API. + +## Access General Settings + +To access general settings, visit the site admin area and click **Settings**. To save the settings, click **Save Settings**. + +## Require Site Admins to Enable Two-factor Authentication + +This setting can make the site more secure by requiring that admins enable two-factor authentication to access site admin functionality. You can use this setting in conjunction with SAML. + +Admins that do not have two-factor authentication enabled may still log in, but will be unable to perform any admin-only functions until they enable and verify two-factor authentication. + +You can use this setting in conjunction with [SAML Single Sign On](/terraform/enterprise/saml/configuration). + +## Organization Creation + +Organization creation can be limited to site administrators or allowed for all users. Limiting organization creation to administrators means that the need for new organizations can be audited and their creation easily monitored. + +When new user accounts are created, if they cannot create their own organizations, they will be unable to access any HCP Terraform resources until they are added to a team. + +## API Rate Limiting + +By default, requests to the HCP Terraform API from a single user or IP address are [limited to 30 requests per second](/terraform/enterprise/api-docs#rate-limiting) to prevent abuse or hogging of resources. Since usage patterns may vary for a given instance, this can be updated to match local needs. A few endpoints have lower limits to prevent certain spam and abuse scenarios. If you receive a rate limited response, the limit will be reflected in the `x-ratelimit-limit` header once triggered. + +## HCP Terraform agents + +HCP Terraform agents allow Terraform Enterprise to communicate with isolated, private, or on-premises infrastructure. + +You can enable agents by clicking the **Enable agents functionality** checkbox. + +Agents also use HTTP polling to acquire operations from Terraform Enterprise. This interval is the minimum number of seconds an agent should wait before polling for again in the event that there are no jobs to execute. + +To set the minimum polling interval, enter a number in the **Minimum polling interval in seconds** field. + +~> **Note:** Using a value that is significantly lower than the previous value may temporarily cause agents to report as **Unknown** because the agent may already be waiting for a longer period of time. + +Refer to [HCP Terraform agents on Terraform Enterprise](/terraform/enterprise/admin/agents-on-tfe) for more details and requirements. + +## Health Assessments + +**Automatic Assessment Interval** sets the minimum amount of time that must pass after a run or health assessment before a new health assessment can start. Decreasing the interval increases the frequency of health assessments. A high volume of concurrent runs and assessments in your organization may result in provider API rate-limiting or performance degradation. + +**Maximum concurrent assessments triggered** sets the number of health assessments that can start for each polling event. HCP Terraform polls all workspaces every 5 minutes to check if they are due for an assessment. This setting prevents running assessments on all of your workspaces at once. + +~> **Note:** If the previous polling event's assessments are still in progress, the number of concurrent active assessments may exceed the **Maximum concurrent assessments triggered** setting. + +## Organization and Workspace Limits + +By default, you can create unlimited organizations and each organization can have unlimited workspaces. However, you can optionally limit these settings. + +To limit organizations, check the **Limit organizations per user** box and enter a number in the **Organizations per user limit** field. + +To limit workspaces, check the **Limit workspaces per organization** box and enter a number in the **Workspaces per organization limit** field. + +## Terraform Run Timeout Settings + +The default timeout setting for Terraform runs are 2h for plans, and 24h for applies. + +These are configurable on a global level, or in the Admin settings at an organization level. + +~> **Note:** The maximum supported timeout for plans or applies is **24h**. + +## Commit Statuses for Untriggered Speculative Plans + +This setting affects Terraform Enterprise's behavior with shared VCS repositories that contain multiple Terraform configurations. + +Workspaces that use part of a shared repository typically don't run plans for changes that don't affect their files; this includes [speculative plans](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) on pull requests. Since "pending" status checks can block pull requests, a workspace will automatically send passing commit statuses for any PRs that don't affect its files. + +However, if this results in sending too many status checks to your VCS provider due to a large number of workspaces sharing one VCS repository, you can disable this behavior and ignore the pending status checks for unaffected workspaces. + +## Remote State Sharing + +The "Share state globally by default" admin setting determines the default value for the "Share state globally" setting on newly created workspaces. + +- When true, a newly created workspace will allow all workspaces in its organization to read its state. +- When false, a newly created workspace will not allow any other workspaces to read its state. + +In all cases, a workspace's state access settings can be changed after creation by workspace admins; this admin setting only affects the initial default value. Additionally, if the `global-remote-state` attribute is provided when creating a workspace via the API, the provided value will be used instead of using the default. + +Refer to the following resources for more information: + +- [Terraform State in HCP Terraform: Accessing State from Other Workspaces](/terraform/enterprise/workspaces/state#accessing-state-from-other-workspaces) +- [Workspace Settings: Remote State Sharing](/terraform/enterprise/workspaces/settings#remote-state-sharing) + +## Allow Speculative Plans on Pull Requests from Forks + +This setting is supported for the following VCS providers: GitHub.com, GitHub.com (OAuth), GitHub Enterprise, Bitbucket Cloud, Azure DevOps Server, Azure DevOps Services. + +By default, this setting is disabled because Terraform Enterprise assumes that forks of a trusted repository are not necessarily themselves trusted. Enabling this setting may allow Terraform Enterprise to execute malicious code or expose sensitive information through [speculative plans](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) on pull requests that originated from a repository fork. + +## Data Retention Policies + + +Data retention policies are exclusive to Terraform Enterprise and unavailable in HCP Terraform. Learn more about Terraform Enterprise. + + +By default, the **Set data retention policy** option is disabled. As a result, no data retention policy is active and Terraform Enterprise retains all data associated with configuration and state versions. + +To set a global data retention policy, enable the **Set data retention policy** setting and choose a duration from the drop-down menu. When a duration is set, Terraform _soft deletes_ the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform deletes it after the set number of days. + +Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection process begins, you can restore soft deleted objects using the APIs described in the [configuration version documentation](/terraform/enterprise/api-docs/configuration-versions) and the [state version documentation](/terraform/enterprise/api-docs/state-versions). Terraform permanently deletes the archivist storage after the garbage collection grace period elapses. + +Organization owners can configure their organizations to inherit or override the global policy. Refer to [Organization settings](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies) for instructions. + +Workspace admins can also configure their workspaces to inherit the parent policy or override the global policy in the workspace settings. Refer to [Workspace settings](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) for instructions. + +## Automated License Utilization Reporting + +Automated license utilization reporting sends license utilization data to HashiCorp without requiring you to manually collect and report them. [Learn about automated license utilization reporting](/terraform/enterprise/deploy/manage/license-report). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/github-app-integration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/github-app-integration.mdx new file mode 100644 index 0000000000..1d787cd017 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/github-app-integration.mdx @@ -0,0 +1,153 @@ +--- +page_title: Integrate with a GitHub App +description: >- + Learn how to integrate Terraform Enterprise with a GitHub App to let organizations access GitHub repositories. +--- + +# Integrate with a GitHub App + +This topic describes how to integrate your Terraform Enterpise deployment with a GitHub App. + +## Introduction + +Site administrators can provision a GitHub App integration that all organizations on the same Terraform Enterprise instance can use to access GitHub repositories. Integrating with a GitHub App offers advantages over connecting to GitHub repositories using GitHub OAuth. Refer to [GitHub Documentation](https://docs.github.com/en/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps) to learn more. + + +## Configuring GitHub App Integration + +These instructions are for using repositories from GitHub.com or Self-hosted GitHub Enterprise with Terraform Enterprise. + +For more information on using a GitHub App and GitHub Permissions in HCP Terraform, see [GitHub Permissions in HCP Terraform](/terraform/cloud-docs/vcs/github-app#github-permissions). + +### Step 1: Configure GitHub App Settings in Terraform Enterprise + +You can integrate with either GitHub.com or a self-hosted GitHub Enterprise instance. + +1. Go to the admin interface and then click **VCS Integrations**. The **VCS Integrations** page appears. + +2. Click **Create global GitHub App**. The **Location** and **GitHub App Owner** options appear. + +3. For the **Location** option, choose if you want to integrate with **GitHub.com** or a **Self-hosted GitHub Enterprise** instance. + + - If integrating with a **Self-hosted GitHub Enterprise** instance, fill in the **HTTP URL** and **API URL** of your GitHub Enterprise instance. + + | Field | Value | + | -------- | ------------------------------------------- | + | HTTP URL | `https://` | + | API URL | `https:///api/v3` | + +4. For the **GitHub App Owner**, choose either **Personal Account** or **Organization Account**. + + - If assigning ownership to a GitHub Organization, fill in the **Organization Name**. + + -> **Note**: You can change this later. See the [Transferring GitHub App Ownership](#transferring-github-app-ownership) section below for more information. + +5. Click **Create global GitHub App**. You will be redirected to the **Create GitHub App** screen on GitHub. + +6. Modify the default GitHub App name if necessary. When done, click **Create GitHub App for [GitHub User Handle]**. + + +-> **Note**: The GitHub App name must satisfy GitHub's requirements. + +### Step 2: Authorize and Install the GitHub App + +In order to start using your GitHub App, you must authorize and install it. + +1. Click **Authorize**. The GitHub Authorization dialog appears. + +2. Accept the authorization. Afterwards, the GitHub installation dialog will appear. + + -> **Note**: If the installation dialog fails to appear, make sure your browser settings allow pop-ups for your Terraform Enterprise site. + +3. Select the repositories you want to grant access to. + +-> **Note**: This will limit which GitHub repositories your workspaces, policy sets, and registry modules have access to. + +### Finished + +Your Global GitHub App for Terraform Enterprise is fully installed and configured. You can now create Terraform workspaces based on the GitHub repositories your Global GitHub App has access to. + +
+ +## GitHub App Management + +### Currently Unsupported Features + +~> **Warning**: Do not modify or remove the default Client Secret, Private Key, or Webhook Secret. + +* GitHub App Client Secret Rotation +* GitHub App Private Key Rotation +* GitHub App Webhook Secret Rotation + +### Required Permissions and Events + +#### Repository permissions + +These permissions are set by default. Do not alter these permissions unless specified to do so in a future Terraform Enterprise release. + +| Permission | Access | +| ------------------ | -------------- | +| Commit statuses | Read and write | +| Contents | Read-only | +| Metadata | Read-only | +| Pull requests | Read-only | + + +#### Required Subscribe Events + +These events are set by default. Do not alter these events unless specified to do so in a future Terraform Enterprise release. + +| Event | Description | +| ------------- | ------------------------------------------- | +| Create | Branch or tag created. | +| Pull Request | Pull request assigned, edited, opened, etc. | +| Delete | Branch or tag deleted | +| Push | Git push to a repository | + +
+ +### Transferring GitHub App Ownership + +During the setup process for your GitHub App, you can choose a default owner for the application. + +If you want to transfer ownership of the GitHub App to another user or organization, follow the [transferring GitHub App ownership](https://docs.github.com/en/developers/apps/managing-github-apps/transferring-ownership-of-a-github-app) instructions. No actions need to be taken within Terraform Enterprise. + +### Removing Global GitHub App from Terraform Enterprise + +~> **Warning**: Do not delete the GitHub App from GitHub until you have first removed it from Terraform Enterprise. + +In order to remove the GitHub App from your Terraform Enterprise instance, you must first remove all installations for the application in GitHub. + +#### Step 1: Remove GitHub App Installations + +~> **Warning**: Uninstalling the application will remove the connections it has to workspaces, policy sets, and registry modules. + +1. Go to the admin interface and then click **VCS Integrations**. The **VCS Integrations** page appears. + +2. If you previously authorized the GitHub App, accessible installations will be shown. Otherwise, you will need to authorize the GitHub App to continue with the removal. + +3. For each installation, click **View in GitHub**. A new tab will open showing the installation settings page within GitHub. + + -> **Note**: You can also find the list of **[Installed GitHub Apps](https://github.com/settings/installations)** on the **Applications** page in GitHub **Settings**. + +4. Locate the **Danger zone** section. + +5. Click **Uninstall** to uninstall the application. Repeat this process for each installation. + +#### Step 2: Remove GitHub App from Terraform Enterprise + + +After you have removed all GitHub App installations, remove the GitHub App from Terraform Enterprise. + +-> **Note**: You may need to refresh the **VCS Integrations** page to verify that all app installations have been removed. + +1. Click the red delete button. A confirmation modal will appear. + +7. In the confirmation modal, click **Delete**. A success message will appear and you will be navigated back to the admin interface home page. + +3. You are now free to delete the GitHub App in GitHub. + +### Additional Resources + +- [About GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps) +- [Differences between GitHub Apps and OAuth Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps) \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/index.mdx new file mode 100644 index 0000000000..40aaaae61f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/index.mdx @@ -0,0 +1,21 @@ +--- +page_title: Terraform Enterprise application administration +description: >- + Use application administration settings to customize your Terraform Enterprise instance. +--- + +# Application administration overview + +Terraform Enterprise is a software distribution that manages a private instance of the HCP Terraform application. + +## Infrastructure administration +- Maintenance +- Upgrades +- Backups +- Monitoring + +## Application administration +- Integrations +- Customize the UI +- Connect to agents +- Policy settings diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/integration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/integration.mdx new file mode 100644 index 0000000000..455cccf375 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/integration.mdx @@ -0,0 +1,70 @@ +--- +page_title: Integrate with external services +description: >- + Integrate with external services to send communications and authenticate users. Learn how to configure cost estimation, and SAML, SMTP, and Twilio integrations. +--- + +# Integrate with External Services + +This topic describes how to integrate Terraform Enterprise with external services so that Terraform Enterprise can send communications and authenticate users. Refer to the [Admin Settings API](/terraform/enterprise/api-docs/admin/settings) for instructions on configuring integrations using the API. + +## Introdution + +You can integrate with the following external services: + +* Cost Estimation +* SAML Single Sign-On +* SMTP +* Twilio + +## Cost Estimation Integration + +Cost Estimation integration allows Terraform Enterprise to estimate costs for resources during a run. Refer to the [usage instructions](/terraform/enterprise/cost-estimation). + +To access the Cost Estimation settings, click **Cost Estimation**. To enable Cost Estimation, check the **Enable Cost Estimation** box on the settings page, configure the settings, and click "Save settings." At least one provider needs to be configured in order to save. + +* **AWS Instance Profile**: If checked this option will be used without need to input the Access Key or Secret Key in the above form (fields will be greyed out). +* **AWS Access Key ID**: The AWS Access Key ID for a given IAM user. The role associated to these credentials must have full access to the "Price List" service and all of that service's resources. Cost Estimation makes API calls in the `us-east-1` region. +* **AWS Secret Key**: The AWS Secret Key pair for the same Access Key ID. +* **GCP Credentials**: The contents of the JSON that is downloaded when you create a GCP Service Account. +* **Azure Client ID**: The Azure Client ID for a given Service Account. The role associated to these credentials must have full access to the `RateCard` service and all of that service's resources. +* **Azure Client Secret**: The Azure Client Secret pair for the same Client ID. +* **Azure Subscription ID**: The Azure Subscription ID for your account. +* **Azure Tenant ID**: The Azure Subscription ID for your account. + +## SAML Integration + +The SAML integration settings allow configuration of a SAML Single Sign-On integration for Terraform Enterprise. To access the SAML settings, click **SAML**. + +-> **Note:** Since enabling SAML is an involved process, there is a [separate SAML section of the documentation](/terraform/enterprise/saml/configuration). Consult those pages for detailed requirements and configuration instructions for both Terraform Enterprise and your IdP. + +To enable SAML, click **Enable SAML single sign-on** under "SAML Settings". Configure the fields below, then click **Save SAML settings**. To update the settings, update the field values, and save. + +The **Enable SAML debugging** option can be used if sign-on is failing. It provides additional debugging information during login tests. It should not be left on during normal operations. + +## SMTP Integration + +SMTP integration allows Terraform Enterprise to send email-based notifications, such as new user invitations, password resets, and system errors. We strongly recommend configuring SMTP. + +To access the SMTP settings, click **SMTP**. To enable SMTP, check the **Enable email sending with SMTP** box on the settings page, configure the settings, and click "Save SMTP settings." + +* **Sender Email**: The address that system mails should come from. A plain email address; do not include a display name. +* **Send test email to**: A sample address to send a test email to. Used to validate the settings when configuring SMTP; not stored. +* **Host** and **Port**: The host and port details for the SMTP server that will be used. +* **Authentication**: The type of authentication used by the server. Options are `none`, `login`, and `plain`. +* **Username**: Username used to authenticate to the server. Not required if the authentication setting is `none`. +* **Password**: Password to authenticate to the server. Not required if the authentication setting is `none`. + +-> **Note**: The SMTP server used with Terraform Enterprise must support connection via SSL with a valid certificate and `STARTTLS` secure communication; `SMTPS` is not supported in Terraform Enterprise. + +## Twilio Integration + +Twilio integration is used to send SMS messages for two-factor authentication. It is optional; application-based 2FA is also supported. + +To access the Twilio settings, click **Twilio**. To enable Twilio, check the **Enable SMS sending with Twilio** box on the settings page and configure the relevant settings: + +* **Account SID**: The unique identifier for your Twilio [application](https://www.twilio.com/docs/usage/api/applications). +* **Auth Token**: The token that allows [authentication](https://support.twilio.com/hc/en-us/articles/223136027-Auth-Tokens-and-How-to-Change-Them) with your Account SID. +* **From Number**: The number the message should come from. Must be registered with Twilio. + +You can also verify the Twilio settings by sending a test message. Enter a number in the **From Number** field and click **Send Test SMS**. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/opa-tool-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/opa-tool-versions.mdx new file mode 100644 index 0000000000..e3eb94ab2e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/opa-tool-versions.mdx @@ -0,0 +1,30 @@ +--- +page_title: Add an Open Policy Agent (OPA) tool version +description: >- + Learn how to add and manage Open Policy Agent (OPA) versions in the UI. +--- + +# Manage Open Policy Agent tool versions + +This topic describes how to specify which version of the Open Policy Agent (OPA) framework Terraform Enterprise uses to monitor compliance. + +## Requirements + +You must have one of the following user roles to access the **OPA Versions** page: + +- Site admin +- Configuration +- Support +- Version maintenance + +## Add an OPA version + +1. Navigate to the **OPA Versions** +1. Click **Add OPA version**. +1. In the **Version** text box, enter the version number you want to add, for example `0.44.0`. +1. Enable the **Enable this version** option. +1. In the **URL** text box, enter `https://github.com/open-policy-agent/opa/releases/download/v0.44.0/opa_linux_amd64_static`. +1. In the **SHA256 Checksum** text box, enter `5ddb21d3fcfca130a47a42e730c05f055c68af6c1b37465879f6c59b10527eae`. +1. Click **Add OPA version** to complete the setup. + +Refer to the [OPA Github repository](https://github.com/open-policy-agent/opa/releases) releases page for additional information. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/registry-sharing.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/registry-sharing.mdx new file mode 100644 index 0000000000..64f1c634bf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/registry-sharing.mdx @@ -0,0 +1,58 @@ +--- +page_title: Share modules and providers from a private registry +description: >- + Use registry sharing to share modules and providers with other organizations in the same Terraform Enterprise instance. Learn how to manage shared registries, stop sharing, and edit registry sharing settings in the UI. +--- + +# Share Modules and Providers from a Private Registry + +This topic describes how to share modules and providers from your private Terraform Enterprise registry. + +## Introduction + +Site administrators can share modules and providers from an organization's private registry with other organizations in the same Terraform Enterprise instance. This allows other organizations to use these modules and providers in their Terraform configuration without needing to ingress or maintain the modules or providers themselves. + +There are two ways to share between organizations: + +1. [Global sharing](#global-sharing): modules and providers from an organization are available to all other organizations in that Terraform Enterprise instance +1. [Partnership sharing](#partnership-sharing): modules and providers from an organization are available to a specific set of organizations in that Terraform Enterprise instance + +**Note:** The two sharing options are mutually exclusive, so turning one on will turn the other one off. This means that if you have configured a set of partnerships for an organization, they will be lost if you switch that organization to use global sharing. + +-> **API:** Refer to the [Admin Organizations API](/terraform/enterprise/api-docs/admin/organizations). + +## Managing Shared Registries + +To access the list of shared registries in the Terraform Enterprise instance, click **Registry**. + +Click on **Select organization** to choose the organization that contains the modules or providers to share. Type the name of the sharing organization or select it from the drop-down. + +Once you select the sharing organization, you can configure the sharing type. + +### Global Sharing + +To share the organization's modules or providers with all other organizations in the Terraform Enterprise instance, click the toggle switch next to **Share modules with all organizations** or **Share providers with all organizations**. + +Click **Share registry** to save the sharing settings. You will be redirected to the initial registry sharing page, which now shows the organization sharing its registry with "All organizations". + +### Partnership Sharing + +To share the organization's modules or providers with a limited group of organizations, the corresponding toggle should be turned off. Add a list of consuming organizations by clicking on the dropdown below and selecting the name(s) of the organizations who will be able to access modules or providers from the sharing organization. If you have many organizations in the dropdown, you can start typing the name to filter the list. + +Once you have selected a list of organizations to share with, click **Share registry** to save the sharing settings. You will be redirected to the initial registry sharing page, which now shows how many organizations the organization is sharing its registry with. + +## Stop Sharing a Registry + +~> **Important**: Removing or changing existing sharing settings can break Terraform workspaces for organizations that are using shared modules or providers. Proceed with caution! + +To stop sharing modules or providers from the **Registry** page, click on the three dots next to any organization that's currently sharing modules or sharing providers. + +Click **Stop sharing**. You will be prompted to confirm the action by typing in the name of the organization. + +## Edit Registry Sharing Settings + +If you wish to change sharing settings for an organization, from the **Registry** page, click on the three dots next to any organization that's currently sharing modules or providers. Click **Edit sharing** and you will be able to modify the sharing settings for that organization. For example, you may wish to: + +- Share with an additional organization (add a consumer) +- Stop sharing with an organization (remove a consumer) +- Change an organization from partnership sharing to global sharing diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/resources.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/resources.mdx new file mode 100644 index 0000000000..118280895d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/resources.mdx @@ -0,0 +1,93 @@ +--- +page_title: Manage Terraform Enterprise accounts and resources +description: >- + Learn how Terraform Enterprise administrators can manage resources, users, organizations, workspaces, runs, and Terraform versions. +--- + +# Manage Accounts and Resources + +This topic describes how Terraform Enterprise site administrators can manage accounts and resources. + +## Introduction + +Terraform Enterprise site administrators have access to all organizations, users, runs, and workspaces. This visibility is intended to provide access to management actions such as adding administrators, updating Terraform versions or adding custom Terraform bundles, suspending or deleting users, and creating or deleting organizations. It also allows for "impersonation" to aid in assisting regular users with issues in the HCP Terraform application. + +-> **API:** Refer to the [Admin Users API](/terraform/enterprise/api-docs/admin/users), [Admin Organizations API](/terraform/enterprise/api-docs/admin/organizations), [Admin Workspaces API](/terraform/enterprise/api-docs/admin/workspaces), [Admin Runs API](/terraform/enterprise/api-docs/admin/runs) and [Admin Terraform Versions API](/terraform/enterprise/api-docs/admin/terraform-versions). + +## Viewing, Searching, and Filtering Lists + +Terraform Enterprise presents each type of account or resource as a searchable list that you can access by clicking the name of the resource. You can search and filter by relevant attributes, and the UI offers pre-existing filters to show useful sets, such as site administrators (users) or **Needs Attention** (workspaces, runs). + +## Managing Users + +To access the list of all users in the Terraform Enterprise instance, click **Users**. + +Selecting a user from the list shows their detail page, which includes their status and any organizations they belong to. The detail page offers four actions: promoting to administrator, suspending, deleting, and impersonating. For users with active [two-factor authentication (2FA)](/terraform/enterprise/users-teams-organizations/2fa), it also offers an administrative option to disable their 2FA in the event that a reset is needed. + +### Promoting a User to Administrator + +This adds the user to the list of site administrators, which grants them access to this administrative area. Because admins have a very wide purview, if SMTP is configured, it will also send an email to the other site administrators notifying them that a user was added. + +To promote a user, click **Promote to admin** on the user detail page. + +### Suspending or Deleting a User + +Suspending a user retains their account, but does not allow them to access any HCP Terraform resources. Deleting a user removes their account completely; they would have to create a new account in order to log in again. + +Suspended users can be unsuspended at any time. Deleted users cannot be recovered. + +To suspend a user, click **Suspend user**. To delete them, click **Delete User** in the "Delete User" section. + +### Impersonating a User + +User impersonation allows Terraform Enterprise admins to access organization and workspace data and view runs. As an administrator, direct access to these resources only supports urgent interventions like deletion or force-canceling; to view and interact with resources, impersonation is required. + +When impersonating a user, a reason is required and will be logged to the audit log. Any actions taken while impersonating will record both the impersonating admin and the impersonated user as the actor. + +Impersonation can be performed from multiple places: + +- From a user details admin page, click **Impersonate**. +- From an organization, workspace, or run details admin page, all of which include a drop-down list of organization owners to impersonate. +- When a site admin encounters a 404 error for a resource that they do not have standard user access to. + +### Resetting Two-Factor Authentication + +If a user has lost access to their 2FA device, a site admin can disable the configured 2FA and allow the user to log in using only their username and password or perform a standard password reset. If the user has active 2FA, a button labeled **Disable 2FA** appears next to the admin promotion button. + +Be sure that the user's identity and the validity of their request have been verified according to appropriate security procedures before disabling their configured 2FA. + +-> **Note:** If the user belongs to an organization that requires 2FA, upon login, they will be redirected to [set it up again](/terraform/enterprise/users-teams-organizations/2fa) before they can view any other part of Terraform Enterprise. + +## Managing Organizations + +The **Organizations** page lets you configure the organizations in your Terraform Enterprise instance. If there are multiple organizations, click each one in the admin list to view its details. + +You can disable or delete organizations, as well as impersonate an owner to modify an organization's settings, profile, and workspaces. You can also control whether the organization can use beta Terraform versions in runs, set timeouts for plans and applies, and set a limit on the number of workspaces that an organization can contain. + +Typically, all organizations on a Terraform Enterprise instance are granted "Premium" plan status to ensure access to all available features. However, it's also possible to set other statuses. An organization whose trial period is expired will be unable to make use of features in the HCP Terraform application. + +## Managing Workspaces and Runs + +The administrative view of workspaces and runs provides limited detail (name, status, and IDs) to avoid exposing sensitive data when it isn't needed. Site administrators can view and investigate workspaces and runs more deeply by impersonating a user with full access to the desired resource. (See [Impersonating a User](#impersonating-a-user) above.) + +### Deleting Workspaces + +A workspace can be administratively deleted, using the **Delete this Workspace** button on its details page, if it should not have been created, or is presenting issues for the application. + +### Force-Canceling Runs + +A run can be administratively force-canceled if it becomes stuck or is presenting issues to the application. Runs can be force-canceled from the run list or the run details page. The run details page also offers the option to impersonate an organization owner for additional details on the run. + +We recommend impersonating a user (if necessary) to view run details prior to force-canceling a run, to ensure that graceful cancellation was attempted, and that the run is no longer progressing. + +## Managing Terraform Versions + +Terraform Enterprise ships with a default list of Terraform versions. However, the addition of new versions after installation is the responsibility of site administrators. + +To add a new version of Terraform, click **Terraform Versions** and then click **Add Terraform Version**. Provide the version number, Linux 64-bit download URL, and SHA256 checksum of the binary. Set the status to **Beta** to make the version available to site administrators, or Enabled to add it for everyone. + +~> **Important:** Terraform Enterprise ships with a default list of Terraform versions. Any modifications to these default Terraform versions will be overwritten. As such, it is recommended to create new Terraform versions instead of modifying the default Terraform versions. + +The versions you add may be recent standard Terraform releases from HashiCorp, or custom Terraform versions. One common use for custom versions is to add a Terraform bundle that includes [pre-installed providers](/terraform/enterprise/run/install-software#custom-and-community-providers) commonly needed by the instance. + +Versions of Terraform can also be modified by clicking them in the list. They can be set to disabled (unavailable for use) if no workspaces are currently using them. The list indicates how many workspaces are currently using a given version. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/sentinel-tool-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/sentinel-tool-versions.mdx new file mode 100644 index 0000000000..1ed6a10395 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/application-administration/sentinel-tool-versions.mdx @@ -0,0 +1,30 @@ +--- +page_title: Manage Sentinel tool versions in Terraform Enterprise +description: >- + Learn how to add and manage Sentinel versions in the Terraform Enterprise user interface. +--- + +# Manage Sentinel tool versions + +This topic describes how to specify which version of Sentinel Terraform Enterprise uses to monitor compliance. + +## Requirements + +You must have one of the following user roles to access the **Sentinel Versions** page: + +- Site admin +- Configuration +- Support +- Version maintenance + +## Add a Sentinel version + +1. Navigate to the **Sentinel Versions** page. +1. Click **Add Sentinel version**. +1. Enter `0.24.2` for **Version**. +1. Check the **Enable this version** box. +1. Enter `https://releases.hashicorp.com/sentinel/0.24.2/sentinel_0.24.2_linux_amd64.zip` for the **URL**. +1. Enter `a17aad9797e7b9b0072c887c2e761703e2bee742ff327011ccec5e6686fc5b8b` as your **SHA256 Checksum**. +1. Click **Add Sentinel version**. + +For more details, refer to the [Sentinel GitHub repository releases page](https://releases.hashicorp.com/sentinel). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/aws.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/aws.mdx new file mode 100644 index 0000000000..f777c0c65e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/aws.mdx @@ -0,0 +1,158 @@ +--- +page_title: AWS resources included in cost estimation in Terraform Enterprise +description: Learn which AWS resources Terraform Enterprise includes in cost estimation. +source: terraform-docs-common +--- + +# AWS resources included in cost estimation + +HCP Terraform can estimate monthly costs for many AWS Terraform resources. + +-> **Note:** Terraform Enterprise requires AWS credentials to support cost estimation. These credentials are configured at the instance level, not the organization level. See the [Application Administration docs](/terraform/enterprise/admin/application/integration) for more details. + +## Supported Resources + +Cost estimation supports the following resources. Not all possible values for attributes of each resource are supported, ex. newer instance types or EBS volume types. + +| Resource | Incurs Cost | +| ------------------------------------------- | ----------- | +| `aws_alb` | X | +| `aws_autoscaling_group` | X | +| `aws_cloudhsm_v2_hsm` | X | +| `aws_cloudwatch_dashboard` | X | +| `aws_cloudwatch_metric_alarm` | X | +| `aws_db_instance` | X | +| `aws_dynamodb_table` | X | +| `aws_ebs_volume` | X | +| `aws_elasticache_cluster` | X | +| `aws_elasticsearch_domain` | X | +| `aws_elb` | X | +| `aws_instance` | X | +| `aws_kms_key` | X | +| `aws_lb` | X | +| `aws_rds_cluster_instance` | X | +| `aws_acm_certificate_validation` | | +| `aws_alb_listener` | | +| `aws_alb_listener_rule` | | +| `aws_alb_target_group` | | +| `aws_alb_target_group_attachment` | | +| `aws_api_gateway_api_key` | | +| `aws_api_gateway_deployment` | | +| `aws_api_gateway_integration` | | +| `aws_api_gateway_integration_response` | | +| `aws_api_gateway_method` | | +| `aws_api_gateway_method_response` | | +| `aws_api_gateway_resource` | | +| `aws_api_gateway_usage_plan_key` | | +| `aws_appautoscaling_policy` | | +| `aws_appautoscaling_target` | | +| `aws_autoscaling_lifecycle_hook` | | +| `aws_autoscaling_policy` | | +| `aws_cloudformation_stack` | | +| `aws_cloudfront_distribution` | | +| `aws_cloudfront_origin_access_identity` | | +| `aws_cloudwatch_event_rule` | | +| `aws_cloudwatch_event_target` | | +| `aws_cloudwatch_log_group` | | +| `aws_cloudwatch_log_metric_filter` | | +| `aws_cloudwatch_log_stream` | | +| `aws_cloudwatch_log_subscription_filter` | | +| `aws_codebuild_webhook` | | +| `aws_codedeploy_deployment_group` | | +| `aws_cognito_identity_provider` | | +| `aws_cognito_user_pool` | | +| `aws_cognito_user_pool_client` | | +| `aws_cognito_user_pool_domain` | | +| `aws_config_config_rule` | | +| `aws_customer_gateway` | | +| `aws_db_parameter_group` | | +| `aws_db_subnet_group` | | +| `aws_dynamodb_table_item` | | +| `aws_ecr_lifecycle_policy` | | +| `aws_ecr_repository_policy` | | +| `aws_ecs_cluster` | | +| `aws_ecs_task_definition` | | +| `aws_efs_mount_target` | | +| `aws_eip_association` | | +| `aws_elastic_beanstalk_application` | | +| `aws_elastic_beanstalk_application_version` | | +| `aws_elastic_beanstalk_environment` | | +| `aws_elasticache_parameter_group` | | +| `aws_elasticache_subnet_group` | | +| `aws_flow_log` | | +| `aws_iam_access_key` | | +| `aws_iam_account_alias` | | +| `aws_iam_account_password_policy` | | +| `aws_iam_group` | | +| `aws_iam_group_membership` | | +| `aws_iam_group_policy` | | +| `aws_iam_group_policy_attachment` | | +| `aws_iam_instance_profile` | | +| `aws_iam_policy` | | +| `aws_iam_policy_attachment` | | +| `aws_iam_role` | | +| `aws_iam_role_policy` | | +| `aws_iam_role_policy_attachment` | | +| `aws_iam_saml_provider` | | +| `aws_iam_service_linked_role` | | +| `aws_iam_user` | | +| `aws_iam_user_group_membership` | | +| `aws_iam_user_login_profile` | | +| `aws_iam_user_policy` | | +| `aws_iam_user_policy_attachment` | | +| `aws_iam_user_ssh_key` | | +| `aws_internet_gateway` | | +| `aws_key_pair` | | +| `aws_kms_alias` | | +| `aws_lambda_alias` | | +| `aws_lambda_event_source_mapping` | | +| `aws_lambda_function` | | +| `aws_lambda_layer_version` | | +| `aws_lambda_permission` | | +| `aws_launch_configuration` | | +| `aws_lb_listener` | | +| `aws_lb_listener_rule` | | +| `aws_lb_target_group` | | +| `aws_lb_target_group_attachment` | | +| `aws_network_acl` | | +| `aws_network_acl_rule` | | +| `aws_network_interface` | | +| `aws_placement_group` | | +| `aws_rds_cluster_parameter_group` | | +| `aws_route` | | +| `aws_route53_record` | | +| `aws_route53_zone_association` | | +| `aws_route_table` | | +| `aws_route_table_association` | | +| `aws_s3_bucket` | | +| `aws_s3_bucket_notification` | | +| `aws_s3_bucket_object` | | +| `aws_s3_bucket_policy` | | +| `aws_s3_bucket_public_access_block` | | +| `aws_security_group` | | +| `aws_security_group_rule` | | +| `aws_service_discovery_service` | | +| `aws_sfn_state_machine` | | +| `aws_sns_topic` | | +| `aws_sns_topic_subscription` | | +| `aws_sqs_queue` | | +| `aws_sqs_queue_policy` | | +| `aws_ssm_maintenance_window` | | +| `aws_ssm_maintenance_window_target` | | +| `aws_ssm_maintenance_window_task` | | +| `aws_ssm_parameter` | | +| `aws_subnet` | | +| `aws_volume_attachment` | | +| `aws_vpc` | | +| `aws_vpc_dhcp_options` | | +| `aws_vpc_dhcp_options_association` | | +| `aws_vpc_endpoint` | | +| `aws_vpc_endpoint_route_table_association` | | +| `aws_vpc_endpoint_service` | | +| `aws_vpc_ipv4_cidr_block_association` | | +| `aws_vpc_peering_connection_accepter` | | +| `aws_vpc_peering_connection_options` | | +| `aws_vpn_connection_route` | | +| `aws_waf_ipset` | | +| `aws_waf_rule` | | +| `aws_waf_web_acl` | | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/azure.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/azure.mdx new file mode 100644 index 0000000000..5647698512 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/azure.mdx @@ -0,0 +1,56 @@ +--- +page_title: Azure resources included in cost estimation in Terraform Enterprise +description: Learn which Azure resources Terraform Enterprise includes in cost estimation. +source: terraform-docs-common +--- + +# Azure resources included in cost estimation + +HCP Terraform can estimate monthly costs for many Azure Terraform resources. + +-> **Note:** Terraform Enterprise requires Azure credentials to support cost estimation. These credentials are configured at the instance level, not the organization level. See the [Application Administration docs](/terraform/enterprise/admin/application/integration) for more details. + +## Supported Resources + +Cost estimation supports the following resources. Not all possible values for attributes of each resource are supported, ex. newer VM sizes or managed disk types. + +| Resource | Incurs Cost | +| ------------------------------------------------------ | ----------- | +| `azurerm_app_service_custom_hostname_binding` | X | +| `azurerm_app_service_environment` | X | +| `azurerm_app_service_plan` | X | +| `azurerm_app_service_virtual_network_swift_connection` | X | +| `azurerm_cosmosdb_sql_database` | X | +| `azurerm_databricks_workspace` | X | +| `azurerm_firewall` | X | +| `azurerm_hdinsight_hadoop_cluster` | X | +| `azurerm_hdinsight_hbase_cluster` | X | +| `azurerm_hdinsight_interactive_query_cluster` | X | +| `azurerm_hdinsight_kafka_cluster` | X | +| `azurerm_hdinsight_spark_cluster` | X | +| `azurerm_integration_service_environment` | X | +| `azurerm_linux_virtual_machine` | X | +| `azurerm_linux_virtual_machine_scale_set` | X | +| `azurerm_managed_disk` | X | +| `azurerm_mariadb_server` | X | +| `azurerm_mssql_elasticpool` | X | +| `azurerm_mysql_server` | X | +| `azurerm_postgresql_server` | X | +| `azurerm_sql_database` | X | +| `azurerm_virtual_machine` | X | +| `azurerm_virtual_machine_scale_set` | X | +| `azurerm_windows_virtual_machine` | X | +| `azurerm_windows_virtual_machine_scale_set` | X | +| `azurerm_app_service` | | +| `azurerm_cosmosdb_account` | | +| `azurerm_cosmosdb_sql_container` | | +| `azurerm_cosmosdb_table` | | +| `azurerm_mysql_database` | | +| `azurerm_network_security_group` | | +| `azurerm_postgresql_database` | | +| `azurerm_resource_group` | | +| `azurerm_sql_server` | | +| `azurerm_sql_virtual_network_rule` | | +| `azurerm_subnet` | | +| `azurerm_subnet_route_table_association` | | +| `azurerm_virtual_network` | | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/gcp.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/gcp.mdx new file mode 100644 index 0000000000..e1660de815 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/gcp.mdx @@ -0,0 +1,42 @@ +--- +page_title: GCP resources included in cost estimation in Terraform Enterprise +description: Learn which GCP resources Terraform Enterprise includes in cost estimation. +source: terraform-docs-common +--- + +# GCP resources included in cost estimation + +HCP Terraform can estimate monthly costs for many GCP Terraform resources. + +-> **Note:** Terraform Enterprise requires GCP credentials to support cost estimation. These credentials are configured at the instance level, not the organization level. See the [Application Administration docs](/terraform/enterprise/admin/application/integration) for more details. + +## Supported Resources + +Cost estimation supports the following resources. Not all possible values for attributes of each resource are supported, ex. new or custom machine types. + +| Resource | Incurs Cost | +| --------------------------------------- | ----------- | +| `google_compute_disk` | X | +| `google_compute_instance` | X | +| `google_sql_database_instance` | X | +| `google_billing_account_iam_member` | | +| `google_compute_address` | | +| `google_compute_subnetwork_iam_member` | | +| `google_folder_iam_member` | | +| `google_folder_iam_policy` | | +| `google_kms_crypto_key_iam_member` | | +| `google_kms_key_ring_iam_member` | | +| `google_kms_key_ring_iam_policy` | | +| `google_organization_iam_member` | | +| `google_project` | | +| `google_project_iam_member` | | +| `google_project_iam_policy` | | +| `google_project_service` | | +| `google_pubsub_subscription_iam_member` | | +| `google_pubsub_subscription_iam_policy` | | +| `google_pubsub_topic_iam_member` | | +| `google_service_account` | | +| `google_service_account_iam_member` | | +| `google_service_account_key` | | +| `google_storage_bucket_iam_member` | | +| `google_storage_bucket_iam_policy` | | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/index.mdx new file mode 100644 index 0000000000..d81c7e6c17 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/cost-estimation/index.mdx @@ -0,0 +1,58 @@ +--- +page_title: Cost estimation overview for Terraform Enterprise +description: >- + Terraform Enterprise can estimate the total cost and delta of resources from + your Terraform configuration. Use cost estimation to get hourly and monthly + cost estimates for each resource. +source: terraform-docs-common +--- + +# Cost estimation overview + +> **Hands-on:** Try the [Control Costs with Policies](/terraform/tutorials/cloud-get-started/cost-estimation) tutorial to practice enabling cost estimation and define a policy to check the total monthly delta. + +HCP Terraform provides cost estimates for many resources found in your Terraform configuration. For each resource an hourly and monthly cost is shown, along with the monthly delta. The total cost and delta of all estimable resources is also shown. + +## Enabling Cost Estimation + +HCP Terraform disables cost estimation by default. To enable cost estimation: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, then navigate to the organization where you want to enable cost estimation. +2. Choose **Settings** from the sidebar, then **Cost Estimation**. +3. Toggle the **Enable cost estimation for all workspaces** setting. +4. Click **Update settings**. + +## Viewing a Cost Estimate + +When enabled, HCP Terraform performs a cost estimate for every run. Estimated costs appear in the run UI as an extra run phase, between the plan and apply. + +The estimate displays a total monthly cost by default; you can expand the estimate to see an itemized list of resource costs, as well as the list of unestimated resources. + +Note that this is just an estimate; some resources don't have cost information available or have unpredictable usage-based pricing. Supported resources are listed in this document's sub-pages. + +## Verifying Costs in Policies + +You can use a Sentinel policy to validate your configuration's cost estimates using the [`tfrun`](/terraform/enterprise/policy-enforcement/import-reference/tfrun) import. The example policy below checks that the new cost delta is no more than $100. A new `t3.nano` instance should be well below that. A `decimal` import is available for more accurate math when working with currency numbers. + +```python +import "tfrun" +import "decimal" + +delta_monthly_cost = decimal.new(tfrun.cost_estimate.delta_monthly_cost) + +if delta_monthly_cost.greater_than(100) { + print("This policy prevents a user from increasing their spending by more than $100 per month in a single run without a warning.") +} + +main = rule { + delta_monthly_cost.less_than(100) +} +``` + +## Supported Resources + +Cost estimation in HCP Terraform supports Terraform resources within three major cloud providers. + +- [AWS](/terraform/enterprise/cost-estimation/aws) +- [GCP](/terraform/enterprise/cost-estimation/gcp) +- [Azure](/terraform/enterprise/cost-estimation/azure) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/index.mdx new file mode 100644 index 0000000000..e471614c11 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/index.mdx @@ -0,0 +1,18 @@ +--- +page_title: Create deployment configuration overview +description: Learn about the deployment configuration file for your runtime environment +--- + +# Create deployment configuration overview + +This topic provides overview information about how to create the deployment configuration file for non-Replicated runtimes. If you are deploying Terraform Enterprise to Replicated, refer [Deploy to Replicated](//terraform/enterprise/deploy/replicated) for instructions. + +## Workflow + +Create a deployment configuration file for your runtime environment and specify the Terraform Enterprise configurations. For example, create a values.yaml if you are deploying to Kubernetes or a compose.yaml file if you are deploying to Docker. The runtime platform starts the Linux container for Terraform Enterprise according to the settings defined in the configuration file. Specify settings to control the following actions: + +1. Access the HashiCorp license: If you do not have a license, contact your HashiCorp account manager. Refer to [Configure a license](/terraform/enterprise/deploy/configuration/license) for instructions. +1. Enable access to external services. Configure ingress and egress ports so that Terraform Enterprise can provision resources and perform other tasks. Refer to [Configure network access](/terraform/enterprise/deploy/configuration/network) for instructions. +1. Enable the operation mode. You can operate Terraform Enterprise in different modes that determine how it manages and stores data. Refer to [Configure operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) for instructions on how to set the mode. +1. Store and retrieve data. You can configure how Terraform Enterprise stores and retrieves data associated with your infrastructure resources. Refer to [Data storage settings overview](/terraform/enterprise/deploy/configuration/storage/) for additional information. +1. Customize the Terraform application. Terraform Enterprise performs Terraform runs in ephemeral containers. It is optional, but you can add custom tools and logic to your Terraform run environment. Refer to [Customize run environment](/terraform/enterprise/deploy/custom-image) for instructions. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/license.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/license.mdx new file mode 100644 index 0000000000..925eb1d532 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/license.mdx @@ -0,0 +1,34 @@ +--- +page_title: Configure a Terraform Enterprise license +description: You must configure a license to deploy Terraform Enterprise to a supported runtime environment. Learn how to acquire and configure a Terraform Enterprise license. +--- + +# Configure a license + +This topic describes how to configure the license so that you can deploy Terraform Enterprise to one of the supported runtimes environments. For information about configuring a Terraform Enterprise for the Replicated platform, refer to [Deploy Terraform Enterprise to Replicated](/terraform/enterprise/deploy/replicated). + + +## Acquiring a new Terraform Enterprise license + +To acquire a new Terraform Enterprise license from HashiCorp, contact your account manager. + +## Apply the Terraform Enterprise license + +There are two ways to apply the new license file on startup: + +- Provide the body of the license file as a string to an environment variable called `TFE_LICENSE`. +- Store the license in a file and provide the file path to an environment variable called `TFE_LICENSE_PATH`. + +## License expiration and termination + +To prevent unexpected outages caused by delays in license updates, HashiCorp licenses provisioned for production use +will not terminate on their expiry date. + +If your license expires, you cannot use it for authentication with the HashiCorp image registry (`images.registry.hashicorp.com`). If you configure your installation to pull directly from the HashiCorp registry and your license expires, you cannot reinstall, scale, or upgrade. You can check your license expiration date using the [`tfectl app license` command](/terraform/enterprise/deploy/reference/cli#review-hashicorp-license-status). + +## License updates + +To update an existing installation with a new license, you will need to modify the `TFE_LICENSE` or `TFE_LICENSE_PATH` +variable and restart the application. + +@include "replicated-and-fdo/admin/license-example-usage-payload.mdx" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/network.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/network.mdx new file mode 100644 index 0000000000..7a3dfa1f46 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/network.mdx @@ -0,0 +1,240 @@ +--- +page_title: Configure network access for Terraform Enterprise installation +description: Linux instances running Terraform Enterprise require network access to send and receive traffic. Learn how to configure network access. +--- + +# Configure network access + +This topic describes how to configure network settings to allow Terraform to send and receive traffic. Refer to [Create deployment configuration overview](/terraform/enterprise/deploy/configuration) for an overview of the configuration process. + +## Overview + +You must configure the Linux instance that runs Terraform Enterprise to allow incoming network traffic across several ports. You must also configure Terraform Enterprise to access several external services so that Terraform can download and update resources. + +Configure the following parameters in your deployment configuration file to configure network access: + +1. Ports for ingress traffic. The Terraform binary accepts traffic from the following sources: + - users + - clients + - VCS + - metrics + - TFE servers +1. Egress destination endpoints. To run Terraform Enterprise in an airgapped environment, you must also whitelist the domains that serve the Terraform Enterprise image from the registry. +1. For Docker deployments, you can also disable access to EC2 instance metadata service. +1. Specify any optional network settings, such cloud provider API endpoints for cost estimation. +1. Specify any specific network settings necessary for your environment, such as allowing traffic through firewalls. + +Refer to [environment variables configuration reference](/terraform/enterprise/deploy/) for information about all environment variables. + + +## Define ingress settings + +Specify the following values in your deployment configuration file to configure access into Terraform Enterprise. Refer to [Configuration reference](/terraform/enterprise/deploy/reference/configuration) for information about all configuration settings. + +### Hostnames + +Specify the following settings in your deployment configuration file to set the hostname: + +- [`TFE_HOSTNAME`](/terraform/enterprise/deploy/reference/configuration#tfe_hostname): This should match the hostname you created when preparing the host environment. Refer to [Assign a DNS hostname](/terraform/enterprise/deploy/prepare-host#assign-a-dns-hostname) for additional information. +- [`TFE_HOSTNAME_SECONDARY`](/terraform/enterprise/deploy/reference/configuration#tfe_hostname): You should only configure this setting if you created a secondary hostname for external-facing endpoints when preparing the host environment. Refer to [Assign a DNS hostname](/terraform/enterprise/deploy/prepare-host#assign-a-dns-hostname) for additional information. + + +### Enable access from users, clients, and VCS + +Specify the following settings in your deployment configuration file to enable ingress from users, clients, and the VCS: + +- `TFE_HTTP_PORT`: Specifies the port for accessing Terraform Enterprise over HTTP. HTTP redirects to HTTPS. The default value is `80`. +- `TFE_HTTPS_PORT`: Specifies the port for accessing Terraform Enterprise over HTTPS. The default is `443`. + +#### Ports for Podman + +Podman does not expose privileged ports. If you are deploying to Podman, specify the variables in the `kube.yaml` pod specification file: + +```yaml +- name: "TFE_HTTP_PORT" + value: "8080" +- name: "TFE_HTTPS_PORT" + value: "8443" +``` + +You must also specify the port values in the `kube.yaml` pod specification file: + +```yaml +"ports": +- "containerPort": 8080 + "hostPort": 80 +- "containerPort": 8443 + "hostPort": 443 +- "containerPort": 9090 + "hostPort": 9090 +``` + +#### Integrate with SaaS version control provider + +To integrate with SaaS VCSs, such as GitHub.com, GitLab.com, Bitbucket Cloud, Azure DevOps Services, you must enable ingress from the public internet so that you can use inbound web hooks to reach Terraform Enterprise. Refer [Webhooks](/terraform/enterprise/vcs#webhooks) for additional information. + +You should also configure appropriate security controls, such as a web application firewall (WAF). Refer to your cloud provider documentation for instructions about deploying a WAF. + +### Enable requests for metrics + +Specify the following variables in your deployment configuration file to enable Terraform Enterprise to receive requests for system metrics: + +- `TFE_METRICS_HTTP_PORT`: TCP port on which Terraform Enterprise handles HTTP metrics requests. Default is `9090`. +- `TFE_METRICS_HTTPS_PORT`: TCP port on which Terraform Enterprise handles HTTPS metrics requests. Default is `9091`. + +The metrics endpoints are optional. You can enable metrics collection by setting `TFE_METRICS_ENABLE` to `true`. + +### Terraform Enterprise servers + +If you plan to operate Terraform Enterprise in `active-active` mode, forward requests to port `8201` to enable high availability requests from Vault. + +## Define egress settings + +Add the following destination endpoints to your deployment configuration file so that Terraform can connect to external services. + +### HashiCorp container registry + +- `https://images.releases.hashicorp.com`: The endpoint hosts release container images. +- `https://helm.releases.hashicorp.com`: The endpoint hosts the helm chart for Kubernetes installation. + +### Domains to whitelist for airgapped environments + +To run Terraform Enterprise in an airgapped environment, you must also whitelist the following domains. This because the service that provides the container image is globally routable and may come from any of the regions: + +- `s3-r-w.us-east-1.amazonaws.com` +- `s3-r-w.us-west-2.amazonaws.com` +- `s3-r-w.eu-central-1.amazonaws.com` +- `s3-r-w.eu-west-1.amazonaws.com` + +Note that the domains are owned by Amazon, not HashiCorp, and may change at any time. Refer to this documentation to verify the domains each time you run the deployment configuration. + +### HashiCorp service APIs + +Terraform Enterprise calls the following hostnames unless you have supplied a custom Terraform bundle. Refer to [Custom and Community Providers](/terraform/enterprise/run/install-software#custom-and-community-providers) +for additional information: + +- `registry.terraform.io` +- `releases.hashicorp.com` +- `https://yy0ffni7mf-dsn.algolia.net/`: Specifies the API endpoint of the Terraform Registry's [Algolia](https://www.algolia.com) application. Terraform Enterprise uses Algolia to index resources in the registry and power the public search feature. +- `reporting.hashicorp.services`: Specifies the license entitlement reporting API endpoint. Refer to [Enable automated license reports](/terraform/enterprise/deploy/manage/license-report) for additional information. + + +### Additional outbound network targets + +Terraform Enterprise also needs egress access to the following systems: + +- Any VCS servers and services you that you plan to use. +- Login or authentication servers if you want to enable ADFS, Okta, or other SAML services. +- Cloud API endpoints that you intend to manage with Terraform +- Third party services that you intend to integrate or manage with the Terraform Enterprise server. + +### Cost estimation APIs + +When [Cost Estimation](/terraform/enterprise/application-administration/integration#cost-estimation-integration) is enabled, Terraform Enterprise uses the following cloud provider's APIs to get up-to-date pricing information: + +- `api.pricing.us-east-1.amazonaws.com` +- `cloudbilling.googleapis.com` +- `prices.azure.com` + +## Specify the Docker network container for run execution + +In the [`TFE_RUN_PIPELINE_DOCKER_NETWORK` configuration](/terraform/enterprise/deploy/reference/configuration#tfe_run_pipeline_docker_network), specify the network address where Docker creates the container Terraform uses to execute runs. This is an optional configuration that enables you to prevent Terraform Enterprise from accessing the EC2 instance metadata service in AWS. Refer to [Disable access to EC2 instance metadata service](#disable-access-to-ec2-instance-metadata-service) for instructions. + +The network must already exist and will not be created automatically. Leave blank to use the default network. Defaults to `""`. + + +## Disable access to EC2 instance metadata service + +1. Create a Docker network. Docker uses this network to create containers that run Terraform Enterprise. We recommend using a name that matches your deployment. The following example creates a network called `tfe-workers`: + + ```shell-session + $ docker network create tfe-workers + ``` + +1. Run the `docker network inspect` command to get the subnet and gateway for the Docker network: + + ```shell-session + $ docker network inspect tfe-workers + ``` + +1. Copy the subnet address from the `docker network inspect` command output so that you can use it in the IP table. In the following example, the subnet is `172.18.0.0/16`: + + ```json + [ + { + "Name": "tfe-workers", + "Id": "10cd24aeba3df774ef2bf1dcb64cadbf2016160fd2cd64bb46f07595e8eb3a83", + "Created": "2024-07-08T13:09:52.596315311-07:00", + "Scope": "local", + "Driver": "bridge", + "EnableIPv6": false, + "IPAM": { + "Driver": "default", + "Options": {}, + "Config": [ + { + "Subnet": "172.18.0.0/16", + "Gateway": "172.18.0.1" + } + ] + }, + "Internal": false, + "Attachable": false, + "Ingress": false, + "ConfigFrom": { + "Network": "" + }, + "ConfigOnly": false, + "Containers": {}, + "Options": {}, + "Labels": {} + } + ] + ``` + +1. Add a rule to the IP table that blocks Terraform Enterprise access to the EC2 instance metadata service. Specify the EC2 instance metadata service address, `169.254.169.254`, as the destination and the subnet address you copied in step 3 as the source. You can use the following command template and replace `` with your subnet address to add the rule using the `iptables` command: + + ```shell-session + $ iptables -I DOCKER-USER -d 169.254.169.254 -s -j DROP + ``` + +1. Ensure that the `TFE_RUN_PIPELINE_DOCKER_NETWORK` environment variable is set to the name of the Docker network you created in your Docker Compose file for deploying Terraform Enterprise. The following example sets the variable to a network named `tfe-workers`: + + ```yaml + services: + tfe: + environment: + TFE_RUN_PIPELINE_DOCKER_NETWORK: tfe-workers + ``` + +When you start Terraform Enterprise, the Terraform Enterprise container will connect to the `tfe-workers` Docker network and apply the IP table rule. + +## Specify integration settings + +You can configure Terraform Enterprise to be accessible over a primary and a secondary hostname. Configuring multiple hostnames lets you federate workloads associated with external services, such as OIDC, version control systems (VCS), and custom run tasks. Configure [`TFE_HOSTNAME_SECONDARY`](/terraform/enterprise/deploy/reference/configuration#tfe_hostname_secondary) to direct integration traffic to a secondary host name and specify `primary` or `secondary` for each integration type: + +- [`TFE_OIDC_HOSTNAME_CHOICE`](/terraform/enterprise/deploy/reference/configuration#tfe_oidc_hostname_choice) +- [`TFE_VCS_HOSTNAME_CHOICE`](/terraform/enterprise/deploy/reference/configuration#tfe_vcs_hostname_choice) +- [`TFE_RUN_TASK_HOSTNAME_CHOICE`](/terraform/enterprise/deploy/reference/configuration#tfe_run_task_hostname_choice) + + +## Specify additional configuration settings + +1. If a firewall is configured on the instance, run one of the following commands to allow traffic to flow out of the `docker0` interface to the instance's primary address. We recommend doing this before you install Docker. + + - To use UFW, run: `ufw allow in on docker0` + - To use firewalld, run: `firewall-cmd --permanent --zone=trusted --change-interface=docker0` + +1. Get a domain name for the instance. Using an IP address to access the product is not supported as many systems use TLS and need to verify that the certificate is correct, which can only be done with a hostname at present. + +1. **For GCP only:** Configure Docker to use an MTU (maximum transmission unit) of `1460`, as required by Google ([GCP Cloud VPN Documentation: MTU Considerations](https://cloud.google.com/network-connectivity/docs/vpn/concepts/mtu-considerations)). + + To configure Docker's MTU, create an `/etc/docker/daemon.json` file with the following content: + + ```json + { + "mtu": 1460 + } + ``` + +1. Ensure that the Docker bridge network address is not being used elsewhere on the network. If it is, refer to the [Docker documentation](https://docs.docker.com/network/bridge/) for information on how to change it. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/configure-mode.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/configure-mode.mdx new file mode 100644 index 0000000000..1ad93623c7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/configure-mode.mdx @@ -0,0 +1,87 @@ +--- +page_title: Configure operational mode for Terraform Enterprise deployments +description: Terraform Enterprise's operational mode determines data storage, which affects resilience and scalability. Learn how to configure the operational mode for your deployment. +--- + +# Configure the operational mode + +This topic describes how to specify the operational mode for your Terraform Enterprise deployment. + +## Introduction + +The operational mode determines where Terraform Enterprise stores and retrieves data, which can impact your backup and restore procedures, disaster recovery procedures, and scaling options. The operational mode is required to deploy Terraform Enterprise for all runtimes except Kubernetes. Refer to [Data storage settings overview](/terraform/enterprise/deploy/configuration/storage) for additional information. + +### Recommended modes + +Use the following guidelines to help you choose the appropriate mode. + +#### `active-active` + +Set `TFE_OPERATIONAL_MODE` to `active-active` under the following conditions: + +- Your environment has an external PostgreSQL server, S3-compatible object storage, and Redis instance. +- You have experience managing a PostgreSQL server, such as Amazon RDS for PostgreSQL, Google Cloud SQL for PostgreSQL, or Azure Database for PostgreSQL. +- You have experience managing an S3-compatible object storage location, such as AWS S3, Azure Blob Storage, Google Cloud Storage, or MinIO. +- You have experience managing a Redis instance, such as AWS ElastiCache for Redis, Azure Cache for Redis, or Google Cloud Memorystore for Redis. +- You want to use native backup and restore features provided by the external PostgreSQL server and S3-compatible object storage. +- You want to scale beyond a single instance of Terraform Enterprise to increase reliability and performance. + +#### `external` + +Set `TFE_OPERATIONAL_MODE` to `external` under the following conditions: + +- Your environment has an external PostgreSQL server, S3-compatible object storage, and Redis instance. +- You have experience managing a PostgreSQL server, such as Amazon RDS for PostgreSQL, Google Cloud SQL for PostgreSQL, or Azure Database for PostgreSQL. +- You have experience managing an S3-compatible object storage location, such as AWS S3, Azure Blob Storage, Google Cloud Storage, or MinIO. +- You have experience managing a Redis instance, such as AWS ElastiCache for Redis, Azure Cache for Redis, or Google Cloud Memorystore for Redis. +- You want to use native backup and restore features provided by the external PostgreSQL server and S3-compatible object storage. +- You want to scale beyond a single instance of Terraform Enterprise to increase reliability and performance. + +#### `disk` + +Set `TFE_OPERATIONAL_MODE` to `disk` under the following conditions: + +- Your environment does not have an external PostgreSQL server or S3-compatible object storage. +- You have experience managing persistent storage, such as an AWS EBS volume, an Azure Managed Disk, a Google Cloud Persistent Disk, or an iSCSI location. +- You are familiar with using command line tools, such as `cp`, `scp`, and `rsync`, to backup and restore data. + +## Requirements + +The requirements depend on which operational mode you choose. + +### `external` mode + +- Refer to the [PostgreSQL configuration requirements](/terraform/enterprise/deploy/configuration/storage/connect-database) for stateful application data storage requirement details. +- Refer to the [data object storage configuration requirements](/terraform/enterprise/deploy/configuration/storage/connect-object) for requirements. + +### `active-active` mode + +- Refer to the [PostgreSQL configuration requirements](/terraform/enterprise/deploy/configuration/storage/connect-database) for stateful application data storage requirement details. +- Refer to the [data object storage configuration requirements](/terraform/enterprise/deploy/configuration/storage/connect-object) for requirements. +- Refer to the [Redis data store configuration requirements](/terraform/enterprise/deploy/configuration/storage/connect-redis) for requirements. + +### `disk` mode + +One of the following mounted disk types is required for the persistent storage volume: + +- AWS EBS +- GCP zonal persistent disk +- Azure disk storage +- iSCSI +- SAN +- A disk physically connected to the host machine + +## Specify operational mode + +Add the `TFE_OPERATIONAL_MODE` variable to your Terraform Enterprise configuration and specify a mode. The following example sets the mode to `external` when deploying to Docker: + +```yaml +name: terraform-enterprise +services: + tfe: + image: images.releases.hashicorp.com/hashicorp/terraform-enterprise: + environment: + TFE_OPERATIONAL_MODE: "external" +``` + +Refer to the [`TFE_OPERATIONAL_MODE` configuration reference](/terraform/enterprise/deploy/reference/configuration) for details about operational mode settings. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/aurora.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/aurora.mdx new file mode 100644 index 0000000000..f2a71b8feb --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/aurora.mdx @@ -0,0 +1,100 @@ +--- +page_title: Connect to a PostgreSQL cluster deployed to Aurora +description: Learn how to connect Terraform Enterprise to a highly-available PostgreSQL database cluster deployed to AWS Aurora. +--- + +# Connect to a PostgreSQL cluster deployed to Aurora + +This topic describes how to connect Terraform Enterprise to a highly-available PostgreSQL cluster deployed to AWS Aurora. + + + +**Connecting to a database cluster is in beta**. These instructions describe an example scenario that we tested and verified for non-production use cases. You should evaluate your requirements and business needs to determine the optimal architecture and configurations for your specific environment. + + + +## Overview + +To connect Terraform Enterprise to a highly-available PostgreSQL cluster deployed to AWS Aurora, deploy the Aurora cluster and specify the cluster endpoint in the Terraform Enterprise configuration. + +It is optional, but you can create and run a test workload against Terraform Enterprise to measure the resilience of your high availability PostgreSQL cluster. + +### AWS Aurora + +AWS Aurora is a managed database service that natively supports high-availability and a writer or cluster endpoint that does not require load balancing. Aurora supports read-only endpoints, but Terraform Enterprise does not support them. + +Refer to the following topics in the AWS documentation for additional information about Aurora: + +- [What is Amazon Aurora?](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraOverview.html) +- [High availability for Amazon Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Concepts.AuroraHighAvailability.html) +- [Cluster endpoints for Amazon Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.Endpoints.Cluster.html) + +## Requirements + +During testing, the following deployment configuration resulted in seven successful failover recoveries after 10 iterations. Refer to [Measure failover resilience](#measure-failover-resilience) for additional information: + +- Release v202409-1 +- Operational mode to either `active-active` or `external` +- Set the [`TFE_DATABASE_HOST` variable](/terraform/enterprise/deploy/reference/configuration#tfe_database_host) an HAProxy load balancer +- Set the [`TFE_DATABASE_RECONNECT_ENABLED`](/terraform/enterprise/deploy/reference/configuration#tfe_database_reconnect_enabled) to ` true` +- Terraform Enterprise nodes hosted on [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) +- Terraform Enterprise deployed to three nodes + +Terraform Enterprise does not support RDS proxy. + +## Deploy an Aurora cluster + +Deploy an RDS cluster with Terraform. Refer to [`rds_cluster` documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_cluster#aurora-with-postgresql-engine) in the Terraform registry for configuration instructions. + +The following example configuration provisions a cluster called `experiment` and two cluster instances: + +```hcl +data "aws_availability_zones" "available" { + state = "available" +} + +resource "aws_rds_cluster" "aurora_postgresql" { + cluster_identifier = "experiment" + engine = "aurora-postgresql" + engine_version = "16.2" + availability_zones = slice(data.aws_availability_zones.available.names, 0, 3) + delete_automated_backups = true + backup_retention_period = 1 + deletion_protection = false + skip_final_snapshot = true + storage_encrypted = true + ... +} + +resource "aws_rds_cluster_instance" "cluster_instances_n" { + count = 2 + identifier = format("%s-aurora-node-%d", "experiment", count.index + 1) + cluster_identifier = aws_rds_cluster.aurora_postgresql.id + instance_class = "db.r5.xlarge" + engine = aws_rds_cluster.aurora_postgresql.engine + engine_version = aws_rds_cluster.aurora_postgresql.engine_version +} +``` + +## Measure failover resilience + +You can collect recovery time objective (RTO) data to assess the resilience of your HA system. Refer to the following topics for additional information: + +- [PostgreSQL database failover](/terraform/enterprise/deploy/manage/failover) +- [Measure failover resilience](/terraform/enterprise/deploy/configuration/storage/connect-database/failover-resilience) + +In the example scenario, we executed test workloads against the instance every 15 seconds for 10 iterations. If the workload did not report success within 10 seconds, we consider the instance unhealthy. The instance is also considered non-operational if any run fails. We considered Terraform Enterprise to be fully operational when five consecutive runs finished successfully. + +We observed the following outcomes after triggering 10 failovers: + +- Seven failed over successfully within approximately one minute. +- Two failed over and returned to partial operation. 30-50 percent of the runs executed after failover continued to fail, but Terraform Enterprise successfully completed some of those runs. Manually restarting the Terraform Enterprise nodes resolved the issues. +- One failover never returned to operation. Manually restarting the Vault process inside the Terraform Enterprise node or fully restarting all nodes resolved the issue. +- Recovery times ranged from a minimum RTO of less than 25 seconds to a maximum of one minute. +- Average RTO was 51 seconds across successful failovers. + +## Troubleshooting + +You may need to manually address issues after a failover to return to functionality. For example, the Vault process may still be connected to a read-only instance if the affected instance can not process runs. + +Refer to [Unable to write to database after a failover](/terraform/enterprise/deploy/troubleshoot/error-messages#unable-to-write-to-database-after-a-failover) in the Terraform troubleshooting documentation for symptoms and solutions. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/failover-resilience.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/failover-resilience.mdx new file mode 100644 index 0000000000..6513ff0e08 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/failover-resilience.mdx @@ -0,0 +1,87 @@ +--- +page_title: Measure failover resilience +description: Learn how to measure database failover resilience for Terraform Enteprise deployments connect to an HA PostgreSQL cluster. +--- + +# Measure failover resilience + +This topic describes how to measure the failover resilience for a Terraform Enterprise deployment connected to a PostgreSQL database cluster. + +## Overview + +You can connect Terraform Enterprise to a database cluster so that the application can fail over to another database instance if there is an issue with the primary instance. Refer to the following topics for additional information: + +- [PostgreSQL database failover](/terraform/enterprise/deploy/manage/failover) +- [Connect to a PostgreSQL cluster](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres-cluster) + +You can test the resilience of your failover system by develping and running test workloads against the database cluster and measuring the recovery time objective (RTO). + +Note that RTO varies significantly based on organizational priorities and the complexity of the services involved. + +## Define test workloads + +You can continuously execute a workload against Terraform Enterprise and measure the time since the last successful execution of the workload. With this continuous measurement running, you can then trigger a failover on the Postgres cluster and record the outage duration. + +The following sequence of steps describe an example workload: + +1. Reset workspace to cleanup any blocking run. +1. Create and upload a configuration version. +1. Create a run. +1. Wait for the plan to finish. +1. Discard the plan. + +## Define a protocol + +Determine what success and failure means in terms of measuring RTO for your instances. The following criteria represent an example protocol: + +1. Execute the workloads every fifteen seconds. + 1. If the workload does not report success within 10 seconds, the instance is unhealthy. + 1. The instance is healthy whenfive consecutive runs complete successfully. + 1. The instance is non-operational if any run fails. +1. [Trigger a failover](#trigger-a-failover). +1. Wait until the system becomes operational. + 1. If the workload does not report success within 10 seconds, the instance is unhealthy. + 1. The instance is healthy whenfive consecutive runs complete successfully. + 1. The instance is non-operational if any run fails. +1. Complete 10 iterations. + +## Trigger a failover + +Create a separate organization and workspace to prevent modifying the initial dataset and to enable you to repeat tests. Determine a mechanism for triggering a failover. For example, if Terraform Enterprise is connected to a database cluster hosted on AWS, you can use the relational database service (RDS) to trigger a failover in the AWS console: + + ```shell-session + $ aws rds failover-db-cluster --db-cluster-identifier --region us-west-2` + ``` + +## Compute metrics + +Compute the RTO by logging the duration between the first failed run and the first of five consecutively successful runs. You can measure RTO using [`go-tfe`](https://github.com/hashicorp/go-tfe) client. + +### Patroni example + +The following table contains example data collected by running test workloads against a Terraform Enterprise deployment connected to a PostgreSQL cluster running on Patroni: + +| Failover | RTO | First failed run | First of five consecutive successful runs | +| --- | --- | --- | --- | +| 1 | 0:03:42 | 17:16:06.275 | 17:19:47.832 | +| 2 | - | - | Terraform Enterprise returned the operation within one minute, but runs continued to fail. Restarting all nodes resolved the issue. | +| 3 | 0:04:56 | 17:34:10.940 | 17:39:07.467 | +| 4 | 0:02:18 | 18:01:50.913 | 18:04:08.902 | +| 5 | - | 18:07:30.912 | Terraform Enterprise returned the operation within one minute, but runs continued to fail. Restarting all nodes resolved the issue. | + +### Aurora example + +The following table contains example data collected by running test workloads against a Terraform Enterprise deployment connected to a PostgreSQL cluster running on Aurora: + +| Failover | RTO | Failover start | First failed run | First of five consecutive successful runs | +| --- | --- | --- | --- | --- | +| 1 | 53.6s | 10:13 | 10:13:37.539 | 10:14:31.186 | +| 2 | 61.3s | 10:17 | 10:17:14.430 | 10:18:15.763 | +| 3 | infinite | 10:21 | 10:21:30.875 | Terraform Enterprise is partially operational, but runs randomly fail.
After restarting the nodes, the application is fully operational. | +| 4 | < 25s | 11:36 | No run failed. Failover succeeded in less than the measurement interval of 25s | NA | +| 5 | 55.5s | 11:43 | 11:43:12.188 | 11:44:07.725 | +| 6 | 57.5s | 11:47 | 11:47:44.293 | 11:48:41.828 | +| 7 | 42.7s | 11:51 | 11:51:43.751 | 11:52:26.485 | +| 8 | infinite | 12:27 | 12:27:16.227 | Terraform Enterprise became unoperational. All nodes went down and all runs failed.
Vault sealed on all three nodes.
Either restart the nodes or restart the Vault process inside the nodes. | +| 9 | infinite | 13:27 | 13:28:00.917 | Terraform Enterprise is operational, but all runs failed.
Restarting all nodes resolved the issue. | +| 10 | 58.6s | 13:50 | 13:50:37.778 | 13:51:36.330 | \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/index.mdx new file mode 100644 index 0000000000..00f1c85ef7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/index.mdx @@ -0,0 +1,31 @@ +--- +page_title: Database connection overview +description: Terraform Enterprise uses an external PostgreSQL database to store stateful application data in external or active-active mode. Learn about connecting external PostgreSQL databases. +--- + +# Database connection overview + +This topic provides overview information about configuring Terraform Enterprise to connect to an +external PostgreSQL database. + +You only need to connect to an external database when operating +Terraform Enterprise in `active-active` or `external` mode. These modes instruct +Terraform Enterprise to store and retrieve data in an externally-managed +database. If you prefer to allow Terraform Enterprise to manage the database, +configure Terraform Enterprise to run in `disk` mode. Refer to +[Configure operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) +for additional information. + +-> **Connecting to HA PostgreSQL is in beta.** Do not deploy beta features in production environments. Provision a dedicated test environment before connecting Terraform Enterprise to an HA PostgreSQL cluster. If you have questions or feedback, contact your HashiCorp account representative. + +## Workflows + +Terraform Enterprise stores stateful application data, such as, workspace +settings, organization settings, run information, and user information in a +PostgreSQL database. + +You can deploy an external database or a cluster of highly-available database nodes and configure Terraform Enterprise to connect to it. +Refer to the following topics for instructions: + +- [Connect to an external PostgreSQL database](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres): Describes how to connecto to a single-node database instance. +- [Connect to a highly-available PostgreSQL cluster](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres-cluster): Describes how to connecto to a cluster of database instances. This functionality is in beta. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/patroni.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/patroni.mdx new file mode 100644 index 0000000000..649d16ffc5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/patroni.mdx @@ -0,0 +1,196 @@ +--- +page_title: Connect to a PostgreSQL cluster deployed to Patroni +description: Learn how to connect Terraform Enterprise to a PostgresSQL cluster deployed to Patroni in high availability mode so that you can enable HA failover workflows. +--- + +# Connect to a PostgreSQL cluster deployed to Patroni + +This topic describes how to connect Terraform Enterprise to a highly-available PostgreSQL cluster deployed to Patroni on Kubernetes. + + + +**Connecting to a database cluster is in beta**. These instructions describe an example scenario that we tested and verified for non-production use cases. You should evaluate your requirements and business needs to determine the optimal architecture and configurations for your specific environment. + + + +## Overview + +Install the `postgres-operator` chart, which creates a Postgres construct that manages PostgreSQL clusters on Kubernetes. Refer to the [Postgres operator documentation](https://postgres-operator.readthedocs.io/en/latest/#scope) for additional information. + +1. Create a custom `values.yaml` file and define the necessary Kubernetes objects, such as the HAProxy and a service that enables the proxy to discover the Patroni pods. +1. Deploy the configurations using the Postgres operator Helm chart. + +It is optional, but you can create and run a test workload against Terraform Enterprise to measure the resilience of your high availability PostgreSQL cluster. + +## Requirements + +During testing, the following deployment configuration resulted in three successful failover recoveries after five iterations. Refer to [Measure failover resilience](#measure-failover-resilience) for additional information. + +### Load balancer + +You must deploy a load balancer between Terraform Enterprise and the PostgreSQL cluster on Patroni. Refer to the [requirements for connecting Terraform Enterprise to a PostgreSQL cluster](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres-cluster#requirements) for additional information. + +The scenario described in these instructions uses an HAProxy. For a production deployment of Patroni on Kubernetes, we recommend using the Kubernetes load balancer service. You can configure the load balancer service in the Patroni cluster manifest. Refer to the [Patroni documentation](https://postgres-operator.readthedocs.io/en/latest/administrator/#load-balancers-and-allowed-ip-ranges) for details. + +### Terraform Enterprise + +We tested the scenario described in this topic against the following Terraform Enterprise deployment: + +- Release v202409-1 +- `active-active` operational mode +- Deployed to [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) +- Deployed on three nodes +- The follow environment variables configured: + - [`TFE_DATABASE_HOST` variable](/terraform/enterprise/deploy/reference/configuration#tfe_database_host) set to an HAProxy load balancer + - [`TFE_DATABASE_RECONNECT_ENABLED`](/terraform/enterprise/deploy/reference/configuration#tfe_database_reconnect_enabled) set to `true`. + +### Patroni + +We tested the scenario described in this topic against the following Patroni deployment: + +- Deployed with three nodes +- Served to Terraform Enterprise through an HAProxy load balancer + +## Configure Kubernetes objects + +Create a `values.yaml` file to override the default Postgres operator values. + +### Define cluster resource defaults + +The Postgres operator Helm chart contains default values for all Patroni clusters deployed using the operator. Refer to the [Zalando Postgres operator values](https://github.com/zalando/postgres-operator/blob/master/charts/postgres-operator/values.yaml) for additional information. + +Specify the resources that the Postgres containers should use in the `configPostgresPodResources` field. The following example configures resource requests, such as CPU and memory limits for the Postgres containers in the pods: + +```yaml +configPostgresPodResources + # CPU limits for the postgres containers + default_cpu_limit: "8" + # CPU request value for the postgres containers + default_cpu_request: "4" + # memory limits for the postgres containers + default_memory_limit: 32Gi + # memory request value for the postgres containers + default_memory_request: 16Gi +``` + +### Define cluster behaviors + +Kubernetes allocates resources to the Patroni cluster according to the [values you define in the `configPostgresPodResources` field](#define-cluster-reource-defaults) and starts individual Postgres clusters according to the cluster manifest. The manifest is a custom resource definition (CRD) that defines parameters for each cluster. Refer to the following Postgres operator topics for additional information about the cluster manifest: + +- [Cluster manifest reference documentation](https://postgres-operator.readthedocs.io/en/latest/reference/cluster_manifest/) +- [Zalando Postgres operator repository](https://github.com/zalando/postgres-operator/tree/master/manifests) + +The following example manifest specifies the cluster configuration we tested for this scenario: + +```yaml +apiVersion: "acid.zalan.do/v1" +kind: postgresql +metadata: + name: patroni + namespace: failover +spec: + teamId: "terraform-enterprise" + volume: + size: 10Gi + numberOfInstances: 3 + users: + cluster_admin: # database owner + - superuser + - createdb + user: [] # role for application foo + databases: + db: user # dbname: owner + postgresql: + version: "15" +``` + +### Discovery service + +Define a service that enables the HAProxy to discover the IP addresses of the Patroni pods. The following example uses the Spilo application for discovery. It discovers all Patroni pods and then uses the HAproxy to route to the master: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: patroni-headless + namespace: failover +spec: + clusterIP: None + selector: + cluster-name: patroni + application: spilo + # spilo-role = "master" + ports: + - port: 5432 + name: postgresql + - port: 8008 + name: api +``` + +### HAProxy + +Define an HAProxy that routes traffic to the primary node by setting the [`/primary` Patroni endpoint](https://patroni.readthedocs.io/en/latest/rest_api.html). + +The HAProxy configuration is crucial to the successful recovery of Terraform Enterprise after a failover. By default, the proxy runs a health check every two seconds, which is too long for many implementations. We recommend configuring HAProxy with an interval of maximum `1s`. + +Refer to [HAProxy documentation](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/service-reliability/health-checks/#change-the-interval) for instructions on how to change the health check interval. + +The following configuration uses the Kubernetes DNS set up in `resolv.conf` and applies server-templates and service names to the HAProxy. It also uses a Kubernetes resolver to resolve the DNS name of the Patroni service. If it is unable to resolve the DNS name, it uses the last known IP address or the `libc` resolver in that order. + +```yaml + global + log stdout format raw local0 + maxconn 2000 + + defaults + log global + mode tcp + option tcplog + timeout connect 5000ms + timeout client 50000ms + timeout server 50000ms + + + resolvers kubernetes + parse-resolv-conf + hold valid 10s + + listen postgres + bind *:5000 + mode tcp + retry-on all-retryable-errors + + option httpchk + http-check send meth HEAD uri /primary + http-check expect status 200 + + default-server inter 1s fall 3 rise 2 on-marked-down shutdown-sessions + + server-template patroni- 1-3 + + patroni-headless.failover.svc.cluster.local:5432 check port 8008 resolvers + kubernetes init-addr last,libc,none +``` + +## Deploy the configurations + +Install the Postgres operator chart and apply the configuration files to deploy Patroni and the HAProxy. Refer to the [Postgres operator documentation](https://postgres-operator.readthedocs.io/en/latest/quickstart/#deployment-options) for instructions on how to deploy. + +## Measure failover resilience + +You can collect recovery time objective (RTO) data to assess the resilience of your HA system. Refer to the following topics for additional information: + +- [PostgreSQL database failover](/terraform/enterprise/deploy/manage/failover) +- [Measure failover resilience](/terraform/enterprise/deploy/configuration/storage/connect-database/failover-resilience) + +In the example scenario, we observed the following outcomes: + +- Recovery times ranging from a minimum RTO of 2m18s to a maximum of 4m56s +- Average RTO of 3m38s across successful failovers. +- Two out of five failovers experienced issues where Terraform Enterprise returned the operation within one minute, but node restarts were needed to resolve continued run failures. + +## Troubleshooting + +You may need to manually address issues after a failover to return to functionality. For example, the Vault process may still be connected to a read-only instance if the affected instance can not process runs. + +Refer to [Unable to write to database after a failover](/terraform/enterprise/deploy/troubleshoot/error-messages#unable-to-write-to-database-after-a-failover) in the Terraform troubleshooting documentation for symptoms and solutions. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/postgres-cluster.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/postgres-cluster.mdx new file mode 100644 index 0000000000..15cc2d40c1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/postgres-cluster.mdx @@ -0,0 +1,195 @@ +--- +page_title: Connect to a highly-available PostgreSQL cluster +description: + Learn how to configure Terraform Enterprise to connect to an external + PostgreSQL database cluster so that your Terraform Enterprise instances can store + stateful application data in a highly-available database. +--- + +# Connect to a PostgreSQL cluster + +This topic describes how to configure Terraform Enterprise to connect to an +external cluster of PostgreSQL database servers. +You only need to complete this task under the following conditions: + +- You want to operate Terraform Enterprise in `active-active` or `external` mode. Refer to [Configure operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) for additional information. +- You want to connect Terraform Enterprise to a PostgreSQL database cluster. To connect to a single PostgreSQL node, refer to [Connect to an external PostgreSQL database](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres). +- You want to configure Terraform Enterprise to failover to a PostgreSQL database replica node. Refer to [PostgreSQL database failover](/terraform/enterprise/deploy/manage/failover) for additional information. + +Before you connect to a highly-available PostgreSQL cluster, review the [Known issues](#known-issues) section so that you are aware of potential issues. + +## Introduction + +Complete the following steps to configure Terraform Enterprise to store and retrieve the data in an externally-managed PostgreSQL cluster: + +1. Prepare the PostgreSQL server to host the data. Preparation includes creating + a user appropriate permissions and creating the extensions in the database. +1. Specify the connection settings in your deployment configuration. If your + server requires additional connection parameters, you must also specify them + in the configuration. +You may need to take additional action to resolve issues related to a failover event. + +## Requirements + +Before proceeding, verify that you meet the following requirements. + +### Server + +One of the following servers is required: + +- PostgreSQL server, such as Amazon RDS for PostgreSQL, version 13.x, 14.4 + and up, 15.x or 16.x + + Note that PostgreSQL v12 will reach end of life on November 12, 2024. As a + result, Terraform Enterprise will no longer v12 after that date. + +- PostgreSQL-compatible database service, such as Amazon Aurora PostgreSQL. +- Self-managed PostgreSQL-compatible server cluster, such as Patroni PostgreSQL + +### User + +Create a PostgreSQL user with the following permissions on the database: + +- Permissions to create, modify, and read all tables and indices on all schemas + within the database. Database owners commonly have these permissions. +- Permissions to create extensions. If you are unable to create a user with the + `CREATE EXTENSION` privilege, refer to [Create extensions](#create-extensions) + for instructions on creating the necessary extensions. + +### Load balancer + +Terraform Enterprise requires a single URL to configure the +PostgreSQL backend. In a cluster, the URL should point to the load +balancer, which handles the distribution of connections to the appropriate +database nodes. + +### Runtime + +You can only connect to a database cluster when deploying Terraform Enterprise to the following runtimes: + + - Nomad + - Kubernetes + - OpenShift + - Podman + - Docker + +For information about connecting to an external database for Replicated deployments, refer to [PostgreSQL Requirements for Terraform Enterprise on Replicated](/terraform/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements). + +## Create extensions + +Create extensions for the `rails`, `vault`, `registry`, and `task_worker` +PostgreSQL schemas. The database server automatically creates these schemas if +they do not already exist. + +Run the following commands on the PostgreSQL server to create the extensions: + +```shell-session +CREATE EXTENSION IF NOT EXISTS "hstore" WITH SCHEMA "rails"; +CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "rails"; +CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA "registry"; +``` + +## Specify PostgreSQL connection settings + +Add the following settings to your Terraform Enterprise configuration: + +- Set the `TFE_DATABASE_HOST` variable to the location of your PostgreSQL + server. Format the location as `HOST[:PORT]`, for example `db.example.com` or + `db.example.com:5432`. Multi host connection strings are not supported. +- Set the `TFE_DATABASE_NAME` variable to the name of the database you want to + store the data in. +- Set the `TFE_DATABASE_USER` variable to the user name you want to use to + access the database. +- Set the `TFE_DATABASE_PASSWORD` variable to the password for the user. +- Set the `TFE_DATABASE_RECONNECT_ENABLED` variable to `true`. + +Refer to +[Database settings](/terraform/enterprise/deploy/reference/configuration#database-settings) +in the configuration reference for addtional information. + +### Additional connection parameters + +Add the `TFE_DATABASE_PARAMETERS` variable to your configuration and specify any +additional connection parameters necessary to connect to the server. + +#### `sslmode` + +When providing extra keyword parameters for the database connection, the +`sslmode` parameter only allows the following values: + +- `require` +- `verify-full` +- `verify-ca` +- `disable` + +When operating Terraform Enterprise in `external` mode, the `sslmode` parameter +is set to `require` by default. When operating Terraform Enterprise in `disk` +mode, the `sslmode` parameter is set to `disable` by default. + +Terraform Enterprise provides a certificates file at +`/etc/ssl/private/terraform-enterprise/bundle.pem`, which is required by the +`verify-full` and `verify-ca` modes. + +Refer to the +[PostgreSQL library documentation](https://www.postgresql.org/docs/12/libpq-ssl.html) +for additional information about using `sslmode`. + +#### Client certificate configuration + +You can configure Terraform Enterprise to use PostgreSQL client certificates to authenticate with the server. When providing client certificates, the database password is not required and the `sslmode` parameter is set to `verify-full`. +Terraform Enterprise requires PostgreSQL server certificate to use Subject Alternative Names (SANs) rather than relying solely on the legacy Common Name field. + +Configure the following settings to use PostgreSQL client certificates: +- Set the `TFE_DATABASE_USE_MTLS` variable to `true`. +- Specify the path to the CA certificate file in the `TFE_DATABASE_CA_CERT_FILE` variable. +- Specify the path to the client certificate file in the `TFE_DATABASE_CLIENT_CERT_FILE` variable. +- Specify the path to the client key in the `TFE_DATABASE_CLIENT_KEY_FILE` variable. + + +## Post-failover tasks + +In the event that Terraform Enterprise fails over to the secondary database node, you may need to perform the following actions. + +### Restart failed runs + +Runs can enter a non-terminal state, such as `pending`, and fail to progress when a failover occurs. This is because Terraform Enterprise may be connected to read-only instances of the database. You can perform one of the following tasks to resolve the non-terminal state: + +- Cancel the run: You can cancel `plan` operations that are unfinished. A `plan` operation in the `pending` state blocks the workspace until it is canceled. You can cancel the run on the run’s page or in the + organization settings. Refer to [Runs]](/terraform/cloud-docs/users-teams-organizations/organizations#runs) in the organization settings documentation for additional information. +- Start a new run: If the operation is finished, but the runs state is still non-terminal, then you cannot cancel the run. Runs in this state do not block the workspace. + +### Restart Terraform Enterprise + +If Terraform Enterprise does not return to full operational +capacity or fully go down after a failover, we recommend +manually restarting the faulty Terraform Enterprise nodes. Restarting +forces Terraform Enterprise to reconnect to the correct PostgreSQL node. + +### Restart the Vault process + +A failover may affect Vault when Terraform Enterprise is connected to a Patroni cluster with `HAProxy` configured to check server status at an interval of one second or longer. +If a failover occurs and Vault is still connected to the read-only node, then Vault can seal. + +A single node can seal Vault and render it non-functional. Requests that Terraform Enterprise routes to the affected instance will fail. Some runs will also fail when Terraform Enterprise is in `active-active` mode and deployed with multiple nodes. + +Restart the Vault process or restart the node to resolve this issue. + +## Known Issues + +Interruptions to the database connection affect ongoing processes and lead to +issues in Terraform Enterprise. These issues are related to network timing and do not occur reliably. +They are also more likely to occur if a failover occurs under high +load. + +Read replicas are not supported. Terraform Enterprise does not distinguish between read and write endpoints. +You must route all database interactions, including reads and writes, through the load balancer to the primary node. +This ensures that Terraform Enterprise always interacts with the correct node. + +Multi-primary topology is not supported. Terraform Enterprise is designed to +operate with a strongly consistent data model. Therefore, we do not recommend using a multi-writer +cluster configuration. In multi-writer setups, data written +to one primary node may not be immediately available to others, leading to +potential data inconsistencies. To maintain data integrity and consistency, +all write operations should be directed to a single primary node. This +guarantees that data is immediately consistent and available across the +system. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/postgres.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/postgres.mdx new file mode 100644 index 0000000000..8f6ccdbe5f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-database/postgres.mdx @@ -0,0 +1,132 @@ +--- +page_title: Configure external PostgreSQL connection +description: + Learn how to configure Terraform Enterprise to connect to an external + PostgreSQL database so that your Terraform Enterprise instances can store + stateful application data. +--- + +# Connect to an external PostgreSQL database + +This topic describes how to configure Terraform Enterprise to connect to an +external PostgreSQL database. You only need to complete this task under the following conditions: + +- You want to operate Terraform Enterprise in `active-active` or `external` mode, which instructs +Terraform Enterprise to store and retrieve data in an externally-managed database. Refer to +[Configure operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) +for additional information. +- You want to connect to a single PostgreSQL node. To connect Terraform Enterprise to an HA PostgreSQL database cluster, refer to [Connect to a highly-available PostgreSQL cluster](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres-cluster). + +## Overview + +Complete the following steps to connect Terraform Enterprise to a single PostgreSQL node: + +1. Create extensions for the database schemas. +1. Specify the connection settings in your deployment configuration. If your + server requires additional connection parameters, you must also specify them + in the configuration. + +## Requirements + +Before proceeding, verify that you meet the following requirements. + +### Server + +One of the following servers is required: + +- PostgreSQL server, such as Amazon RDS for PostgreSQL, version 13.x, 14.4 + and up, 15.x or 16.x + + + Note that PostgreSQL v12 will reach end of life on November 12, 2024. As a + result, Terraform Enterprise will no longer v12 after that date. + + +- PostgreSQL-compatible server, such as Amazon Aurora PostgreSQL. + +### User + +Create a PostgreSQL user with the following permissions on the database: + +- Permissions to create, modify, and read all tables and indices on all schemas + within the database. Database owners commonly have these permissions. +- Permissions to create extensions. If you are unable to create a user with the + `CREATE EXTENSION` privilege, refer to [Create extensions](#create-extensions) + for instructions on creating the necessary extensions. +- The `rails`, `vault`, `registry`, `task_worker`, and `terraform_enterprise` PostgreSQL schemas are required. We recommend allowing the PostgreSQL user to create schemas so that Terraform Enterprise can create them automatically. If the PostgreSQL user does not have permissions to create schemas, they must be created prior to installation. + + + Note that if you are changing the database user, ensure the new user is the owner of all + enum types in the database to avoid failures for any potential migrations that + attempt to `ALTER TYPE`. + + +## Create extensions + +Create extensions for the `rails`, `vault`, `registry`, and `task_worker` +PostgreSQL schemas. The database server automatically creates these schemas if +they do not already exist. + +Run the following commands on the PostgreSQL server to create the extensions: + +```shell-session +CREATE EXTENSION IF NOT EXISTS "hstore" WITH SCHEMA "rails"; +CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "rails"; +CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA "registry"; +``` + +## Specify PostgreSQL connection settings + +Add the following settings to your Terraform Enterprise configuration: + +- Set the `TFE_DATABASE_HOST` variable to the location of your PostgreSQL + server. Format the location as `HOST[:PORT]`, for example `db.example.com` or + `db.example.com:5432`. Multi host connection strings are not supported. +- Set the `TFE_DATABASE_NAME` variable to the name of the database you want to + store the data in. +- Set the `TFE_DATABASE_USER` variable to the user name you want to use to + access the database. +- Set the `TFE_DATABASE_PASSWORD` variable to the password for the user. + +Refer to +[Database settings](/terraform/enterprise/deploy/reference/configuration#database-settings) +in the configuration reference for additional information. + +### Additional connection parameters + +Add the `TFE_DATABASE_PARAMETERS` variable to your configuration and specify any +additional connection parameters necessary to connect to the server. + +#### `sslmode` + +When providing extra keyword parameters for the database connection, the +`sslmode` parameter only allows the following values: + +- `require` +- `verify-full` +- `verify-ca` +- `disable` + +When operating Terraform Enterprise in `external` mode, the `sslmode` parameter +is set to `require` by default. When operating Terraform Enterprise in `disk` +mode, the `sslmode` parameter is set to `disable` by default. + +Terraform Enterprise provides a certificates file at +`/etc/ssl/private/terraform-enterprise/bundle.pem`, which is required by the +`verify-full` and `verify-ca` modes. + +Refer to the +[PostgreSQL library documentation](https://www.postgresql.org/docs/12/libpq-ssl.html) +for additional information about using `sslmode`. + +#### Client certificate configuration + +You can configure Terraform Enterprise to use PostgreSQL client certificates to authenticate with the server. When providing client certificates, the database password is not required and the `sslmode` parameter is set to `verify-full`. +Terraform Enterprise requires PostgreSQL server certificate to use Subject Alternative Names (SANs) rather than relying solely on the legacy Common Name field. + +Configure the following settings to use PostgreSQL client certificates: + +- Set the `TFE_DATABASE_USE_MTLS` variable to `true`. +- Specify the path to the CA certificate file in the `TFE_DATABASE_CA_CERT_FILE` variable. +- Specify the path to the client certificate file in the `TFE_DATABASE_CLIENT_CERT_FILE` variable. +- Specify the path to the client key in the `TFE_DATABASE_CLIENT_KEY_FILE` variable. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-object.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-object.mdx new file mode 100644 index 0000000000..c847117e93 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-object.mdx @@ -0,0 +1,92 @@ +--- +page_title: Configure data object storage +description: Learn how to configure the Terraform Enterprise connection to an S3-compatible data storage service. +--- + +# Configure data object storage + +This topic describes how to configure Terraform Enterprise to connect to an external data object service. This step is only required when Terraform Enterprise is configured to operate in `external` or `active-active` mode. Refer to [Data storage settings overview](/terraform/enterprise/deploy/configuration/storage) for additional information. + +## Introduction + +Terraform Enterprise stores artifacts that it produces during operation, such as state files, plan files, run logs, and configuration versions, in an S3-compatible storage service. Complete the following steps to configure the connection to an externally-managed data object storage system: + +1. In your object storage service, create a dedicated user that has permissions to access and manage the storage resources. Refer to the documentation for your object storage service for instructions. +1. Configure the connection settings in the Terraform Enterprise deployment configuration. + +## Requirements + +- Any S3-compatible object storage service, GCP Cloud Storage, or Azure blob storage. +- A bucket on the object storage platform for Terraform Enterprise to use. Your infrastructure provider may require the bucket to be in the same region as the Terraform Enterprise instance. +- Disable any lifecycle rules that would delete, archive, or transition objects in the object storage container. Terraform Enterprise expects to manage all data in the object storage service, so any lifecycle operations may result in unexpected data inconsistencies. + +## Configure connection settings + +1. Add the `TFE_OBJECT_STORAGE_TYPE` variable to the configuration and set one of the following storage types: + + - `s3`: Stores objects in an AWS S3 bucket. + - `azure`: Stores objects in an Azure blob. + - `google`: Stores objects in Google's cloud platform. + + Refer to the [`TFE_OBJECT_STORAGE_TYPE` reference documentation](/terraform/enterprise/deploy/reference/configuration#tfe_object_storage_type) for additional information. + +1. Configure the connection settings for the object type. + + + + + + ```yaml + ... + env: + variables: + TFE_OBJECT_STORAGE_TYPE: s3 + TFE_OBJECT_STORAGE_S3_BUCKET: + TFE_OBJECT_STORAGE_S3_REGION: + TFE_OBJECT_STORAGE_S3_USE_INSTANCE_PROFILE: + secrets: + TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: + TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: '' + ``` + + Refer to the [S3-compatible storage configuration reference](/terraform/enterprise/deploy/reference/configuration#s3-compatible-storage) for information about all available settings. + + + + + ```yaml + ... + env: + variables: + TFE_OBJECT_STORAGE_TYPE: azure + TFE_OBJECT_STORAGE_AZURE_ACCOUNT_NAME: + TFE_OBJECT_STORAGE_AZURE_CONTAINER: + TFE_OBJECT_STORAGE_AZURE_ENDPOINT: + secrets: + TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY: '' + ``` + + Refer to the [Azure blob storage configuration reference](/terraform/enterprise/deploy/reference/configuration#azure-blob-storage-settings) for information about all available settings. + + + + + + ```yaml + ... + env: + variables: + TFE_OBJECT_STORAGE_TYPE: google + TFE_OBJECT_STORAGE_GOOGLE_BUCKET: + TFE_OBJECT_STORAGE_GOOGLE_PROJECT: + secrets: + TFE_OBJECT_STORAGE_GOOGLE_CREDENTIALS: + ``` + + Refer to the [Google cloud platform storage configuration reference](/terraform/enterprise/deploy/reference/configuration#google-cloud-platform-storage) for information about all available settings. + + + + + + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-redis.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-redis.mdx new file mode 100644 index 0000000000..7399bec47a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-redis.mdx @@ -0,0 +1,137 @@ +--- +page_title: Configure Redis data store connection +description: Learn how to configure the connection to an externally-managed Redis data store when operating Terraform Enterprise in `active-active` mode. +--- + +# Configure Redis data store connection + +This topic describes how to configure Terraform Enterprise connection to an externally-managed Redis data store. This step is only necessary when operating Terraform Enterprise in an `active-active` operational mode. To allow Terraform Enterprise to self-manage Redis, configure Terraform Enterprise to run in `disk` operational mode on a compatible runtime platform, such as `Docker` or `Podman`. Refer to [Configure operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) for additional information. + +## Introduction + +Terraform Enterprise uses Redis to cache and manage the background job scheduler queue across available hosts. Redis server configuration is required for any runtime platform configured to operate in `active-active` mode. You can operate Terraform Enterprise in `active-active` mode on the following runtime platforms: + +- Kubernetes +- OpenShift +- Nomad + +## Requirements + +Before proceeding, ensure that your environment meets the following requirements: + +- Either a cloud-managed or self-hosted Redis server is required. +- Terraform Enterprise supports Redis server 6 and 7. We recommend using version 7. +- Redis Cluster is not supported. + +Example Redis servers: + +- [Amazon ElastiCache for Redis](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) +- [Official Redis Docker container](https://hub.docker.com/_/redis) + +### Secure Redis servers + +For secure Redis servers, create a user with read and write access. + +### TLS requirements + +Verify that you meet the following requirements when TLS is required to connect to the Redis server: + +- A valid TLS certificate and key are configured on the Redis server. +- The Redis server is properly configured to accept TLS connections. +- The Terraform Enterprise client is configured to use TLS when connecting to Redis. Refer to the [TLS configuration reference](/terraform/enterprise/deploy/reference/configuration#tls-settings) for additional information. + +For detailed information on configuring TLS for Redis, refer to the [official Redis documentation on encryption](https://redis.io/docs/latest/operate/oss_and_stack/management/security/encryption/). + +## Specify Redis connection settings +You can connect to either a Redis standalone instance, or a Redis Enterprise instance in non-clustering mode. +The redis authentication can be configured for all Redis configurations. + +### Authentication +You can configure Redis to use the default user and require a password. +```redis.conf +requirepass +``` + +In that case you would configure Terraform Enterprise +``` + TFE_REDIS_USE_AUTH: true + TFE_REDIS_PASSWORD: +``` + +You can also configure Redis with [ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/) since Redis 6. +```redis.conf +user on > ~* &* +@all +``` + + +If you use a Redis user, it is crucial that they have sufficient permissions. +In our testing, we used the following permissions `~* &* +@all`. + + +In that case, you would configure Terraform Enterprise with the following environment variables: +``` + TFE_REDIS_USE_AUTH: true + TFE_REDIS_USER: + TFE_REDIS_PASSWORD: +``` + +### Redis Standalone + +Add the following settings to your Terraform Enterprise configuration: + +- Set the `TFE_REDIS_HOST` variable to the location of your Redis server. Format the location as `HOST[:PORT]`, for example `redis.example.com` or `redis.example.com:6379`. +- Set the `TFE_REDIS_USE_TLS` variable to `true` if your Redis server requires TLS. Defaults to `false`. +- Set the `TFE_REDIS_USE_AUTH` variable to `true` if your Redis server requires authentication. +- Set the `TFE_REDIS_PASSWORD` variable to the password for the user. + +Refer to [Redis settings](/terraform/enterprise/deploy/reference/configuration#redis-settings) in the configuration reference for additional information. + +### Redis Enterprise + +Terraform Enterprise can use Redis Enterprise in non-clustering mode as it's Redis service. To do so, you must +configure a separate Redis endpoint for `sidekiq`, an internal component. This +requirement exists because `sidekiq` and other components that rely on Redis must be kept +separate. In normal operation, this is accomplishing using numbered Redis databases, which +are not supported in Redis Enterprise. By defining a separate endpoint for `sidekiq` usage, +Terraform Enterprise will use the default database `0` while still maintaining separation between `sidekiq` and +other components. + +Add the following settings to your Terraform Enterprise configuration: + +- Set the `TFE_REDIS_SIDEKIQ_HOST` variable to the location of your Redis server. Format the location as `HOST[:PORT]`, for example `redis.example.com` or `redis.example.com:6379`. +- Set the `TFE_REDIS_SIDEKIQ_USE_TLS` variable to `true` if your Redis server requires TLS. Defaults to `false`. +- Set the `TFE_REDIS_SIDEKIQ_USE_AUTH` variable to `true` if your Redis server requires authentication. +- Set the `TFE_REDIS_SIDEKIQ_PASSWORD` variable to the password for the user. + +### Redis Sentinel + + +Redis Sentinel is not supported for Terraform Enterprise on Replicated. + + +Terraform Enterprise can use Redis Sentinel as a highly available Redis service. Read more about highly available Redis +services with Redis Sentinel in the [Redis Sentinel documentation](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/). + +Terraform Enterprise queries Redis Sentinel instances to determine which Redis instance is active master. Terraform Enterprise performs queries while Redis replicates transaction data to other replicas. + +You cannot use Redis Sentinel and [Redis Enterprise](#redis-enterprise) in the same Terraform Enterprise deployment. + +Use the following settings in your Terraform Enterprise configuration to use Redis Sentinel. Refer to the [Configuration reference](/terraform/enterprise/deploy/reference/configuration) for information about all configuration settings: +- Set the `TFE_REDIS_SENTINEL_ENABLED` variable to `true` in order to use Redis Sentinel. +- Set the `TFE_REDIS_SENTINEL_HOSTS` variable to a comma separated list of the locations of Redis Sentinel hosts. Format the locations as `HOST[:PORT],HOST[:PORT],...`, for example `redis-sentinel-1.example.com,redis-sentinel-2.example.com:26379`. +- Set the `TFE_REDIS_SENTINEL_LEADER_NAME` variable to the name of a service, such as `main`. Terraform Enterprise queries Redis Sentinel for the service to discover an active Redis host. This name should return a valid Redis service location when issuing a `SENTINEL GET-MASTER-ADDR-BY-NAME ` command to Redis Sentinel. +- Set the `TFE_REDIS_SENTINEL_USERNAME` variable to the username for the Redis Sentinel user. This setting is optional and is used to authenticate with Redis Sentinel instances. +- Set the `TFE_REDIS_SENTINEL_PASSWORD` variable to the password for the Redis Sentinel user. This setting is optional and is used to authenticate with Redis Sentinel instances. +- Set the `TFE_REDIS_USER` variable to the username for the Redis user. This setting is optional and is used to authenticate with Redis instances. +- Set the `TFE_REDIS_PASSWORD` variable to the password for the Redis Sentinel user. This setting is optional and is used to authenticate with Redis instances. + +### Failover benchmarks for Redis Sentinel + +We tested failover performance for a Terraform Enterprise deployment connected to a Redis Sentinel cluster. The cluster consisted of three Sentinel instances and three Redis instances. We observed the following outcomes: + +- Failover events that were manually triggered through Redis Sentinel showed no observable down time in Terraform Enterprise. This suggests a high degree of safety in planned maintenance operations. +- The recovery time objective (RTO) during manually triggered failover events ranged from 47s to 2m10s. +- The average RTO was 1m16s across successful failovers. +- One out of 16 failovers experienced issues that required Terraform Enterprise node restarts to resolve continued run failures. + +Terraform Enterprise performance when using Redis Sentinel depends on how Redis Sentinel is configured to monitor and recover from Redis instance problems. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-vault.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-vault.mdx new file mode 100644 index 0000000000..0c2072e405 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/connect-vault.mdx @@ -0,0 +1,34 @@ +--- +page_title: Connect to an external Vault server +description: Using an external Vault server can help satisfy data encryption and auditing compliance requirements. Learn how to connect external Vault servers. +--- + +# Connect to an external Vault server + +This topic describes how to configure Terraform Enterprise to connect to an external Vault server. + +## Introduction + +Using an external Vault server may be necessary if your organization is subject to specific data encryption and auditing compliance requirements. The internal Vault server shipped with Terraform Enterprise that is suitable for most cases. + +You should only use an external Vault server if you have experience managing Vault in production. You are responsible for all Vault server operations, including sealing, unsealing, and replication. + +Do not configure multiple Terraform Enterprise instances to use the same namespace on an external Vault server unless they are part of a Terraform Enterprise deployment in `active-active` mode because doing so will result in data loss. Refer to [Configure the operational mode](/terraform/enterprise/deploy/configuration/configure-mode) for additional information about operational modes. + +Complete the following steps to connect to Terraform Enterprise to an external Vault server: + +1. Configure the Vault server: You must enable settings and create policies that allow Terraform Enterprise to connect to Vault. +1. Specify the Vault settings in the Terraform Enterprise configuration: Refer to the [deployment overview](/terraform/enterprise/deploy) for additional information about configuring Terraform Enterprise. + +## Requirements + +You must configure the settings for your external Vault connection before the initial Terraform Enterprise installation. You can only change the configuration after installing Terraform Enterprise using the [backup and restore API](/terraform/enterprise/deploy/manage/backup-restore). + +## Specify Vault settings + +Add the following settings to your Terraform Enterprise configuration: + +- Set `TFE_VAULT_USE_EXTERNAL` to `true` +- Set `TFE_VAULT_ADDRESS` to the address of your Vault server. +- Set `TFE_VAULT_ROLE_ID` to the Vault secret ID. +- Configure any additional settings specific to your implementation. Refer to the [Vault settings reference](/terraform/enterprise/deploy/reference/configuration#vault-settings) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/index.mdx new file mode 100644 index 0000000000..561d8de438 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/configuration/storage/index.mdx @@ -0,0 +1,50 @@ +--- +page_title: Data storage settings overview +description: Learn about Terraform Enterprise data storage and management configurations, including operational modes, PostgreSQL database connection settings, Redis connection settings, and external Vault server settings +--- + +# Data storage settings overview + +This topic provides an overview of data storage and management configurations for Terraform Enterprise. + +## Overview + +You can configure Terraform Enterprise to run as a self-contained application that manages the associated data storage or as an integrated installation that connects to externally-managed data storage systems. Complete the following steps: + +1. Decide on a Terraform Enterprise architecture and determine which data storage systems you must deploy and maintain externally. +1. Determine which operational mode aligns with how you want to manage data storage for your organization. +1. Deploy the external data storage systems and connect to them in your deployment configuration file. + +## Data storage systems + +Terraform Enterprise uses the following types of storage systems to store data associated with your deployment: + +- **PostgreSQL database**: Terraform Enterprise stores stateful application data, workspace settings, organization settings, run information, and user information in a PostgreSQL database. + + Note that PostgreSQL v12 will reach end of life on November 12, 2024. As a + result, Terraform Enterprise will no longer v12 after that date. + + +- **S3-compatible storage service**: Terraform Enterprise stores artifacts that it produces during operation, such as state files, plan files, run logs, and configuration versions, in an S3-compatible storage service. +- **Vault**: Terraform Enterprise stores encryption keys in Vault that encrypt and decrypt data objects. By default, Terraform Enterprise stores the keys in the internal Vault server, but if your organization has specific data encryption and auditing requirements, you can connect to an external Vault server to manage the data instead. +- **Redis data store**: You can configure Terraform to cache application data in a Redis data store. This system is optional but recommended to improve performance. + +### Operational modes + +You must choose an operational mode before you install and deploy Terraform Enterprise. The operation mode determines where Terraform Enterprise stores its data. Where you store Terraform Enterprise data can impact your backup and restore procedures, disaster recovery procedures, and scaling options. + +The following table provides an overview of how the operational mode directs Terraform Enterprise to store data. Refer to [Configure the operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) for instructions: + +| Mode | PostgreSQL | Object storage | Vault | Redis | +| --- | --- | --- | --- | --- | +| `external` | External. You manage outside of Terraform Enterprise. | External. You manage outside of Terraform Enterprise. | PostgreSQL database unless you specify an external Vault server. | Docker volume on the instance. | +| `active-active` | External. You manage outside of Terraform Enterprise. | External. You manage outside of Terraform Enterprise. | PostgreSQL database unless you specify an external Vault server. | External. You manage outside of Terraform Enterprise. | +| `disk` | Internal directory on the instance. You manage persistent storage. | Internal directory on the instance. You manage persistent storage. | PostgreSQL database unless you specify an external Vault server. | Docker volume on the instance. | + + + + + + + + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/custom-image.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/custom-image.mdx new file mode 100644 index 0000000000..63505ab043 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/custom-image.mdx @@ -0,0 +1,47 @@ +--- +page_title: Build and deploy a custom worker image +description: >- + Terraform Enterprise requires a custom worker image to add custom tools and logic to the run enviornment. Learn how to build and run a custom worker image. +--- + +# Build and deploy a custom worker image + +This topic describes how to build and deploy a custom worker image so that you can add custom tools or logic to your Terraform run environments. + +## Introduction + +Terraform Enterprise performs Terraform runs in ephemeral containers using a built-in `tfc-agent` container image by default. To add custom tools or logic to your Terraform run environment, you must build a custom image and configure Terraform Enterprise to use it. + +## Requirements + +The base image must be `hashicorp/tfc-agent:1.6.0` or later. + +## Dockerfile + +Build your custom image using the below `Dockerfile`. + +```Dockerfile +FROM hashicorp/tfc-agent:latest + +# Switch the to root user in order to perform privileged actions such as +# installing software. +USER root + +# Install sudo. The container runs as a non-root user, but people may rely on +# the ability to apt-get install things. +RUN apt-get -y install sudo + +# Permit tfc-agent to use sudo apt-get commands. +RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoers.d/50-tfc-agent + +# Switch back to the tfc-agent user as needed by Terraform agents. +USER tfc-agent +``` + +## Agent + +Update the environment variable `TFE_RUN_PIPELINE_IMAGE` in your yaml file: + +```yaml +TFE_RUN_PIPELINE_IMAGE: registry.example.com/example/tfc-agent:custom-tag +``` \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/docker/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/docker/index.mdx new file mode 100644 index 0000000000..739bfabf62 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/docker/index.mdx @@ -0,0 +1,341 @@ +--- +page_title: Deploy Terraform Enterprise to Docker overview +description: Learn how to deploy Terraform Enterprise to Docker using Docker Compose. +--- + +# Deploy Terraform Enterprise to Docker + +This topic describes how to deploy Terraform Enterprise to Docker using Docker Compose. You can use another installation method, but we recommend Docker Compose because it simplifies managing the necessary Docker volumes and container configuration. + +## Overview + +Complete the following steps to install Terraform Enterprise: + +1. Complete the prerequisites +1. Set up the installation folders and files +1. Download and install the Docker image +1. Apply the deployment installation + +Complete post installation tasks, such creating the initial admin user account and configuring service management controls. + + +## Prerequisites + +Complete the following tasks before attempting to install Terraform Enterprise. + +### Prepare the deployment environment + +Provide a DNS hostname for Terraform Enterprise and the associated TLS certificate. Additionally, you must configure your network so that your host can receive and send traffic. Refer to [Prepare the host environment](/terraform/enterprise/deploy/prepare-host) for details about preparing the host environment. + +### Deploy storage systems for `active` and `external` mode + +If you intend to operate Terraform Enterprise in `active` or `external` mode, deploy the database and other storage devices so that Terraform can connect to them when the application starts. Refer to [Data storage settings overview](/terraform/enterprise/deploy/configuration/storage) for additional information. + +### Create the deployment configuration + +Create a deployment configuration file and specify settings for the operational mode, license, TLS certificates, and network configuration. Add any additional configurations necessary for your environment. Refer to [Configuration file overview](/terraform/enterprise/deploy/configuration/) for additional information. + + +## Set up installation folders and files + +1. Connect to the host instance. +1. Create a dedicated directory for the Terraform Enterprise installation files. +1. Navigate to the installation directory. +1. Create a `certs` directory. +1. Place your TLS certificate (`cert.pem`), TLS private key (`key.pem`), and CA certificates bundle (`bundle.pem`) inside inside the`certs` directory. If you do not have a CA certificates bundle, place your TLS certificate (`cert.pem`) inside `bundle.pem` instead. +1. Place your deployment configuration file into the Terraform Enterprise installation directory. Refer to [Example deployment configurations](#example-deployment-configurations) for pre-formatted configurations that you can copy and modify. Refer to the [configuration reference](/terraform/enterprise/deploy/reference/configuration) for information about all deployment configuration settings. + +## Download and install the image + +1. Log in to the Terraform Enterprise container image registry, using `terraform` + as the username, and your Hashicorp Terraform Enterprise license as the password: + + ```shell-session + $ echo "" | docker login --username terraform images.releases.hashicorp.com --password-stdin + ``` + +1. Pull the Terraform Enterprise image from the registry. + + ```shell-session + $ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + +## Apply the deployment configuration + +1. Spin up your Terraform Enterprise container by running: + + ```shell-session + $ docker compose up --detach + ``` + +1. In a separate terminal session you can monitor the logs by running the following command: + + ```shell-session + $ docker compose logs --follow + ``` + +1. Monitor the health of the application until it starts reporting healthy with the following command: + + ```shell-session + $ docker compose exec tfe tfe-health-check-status + ``` + +1. If you are operating Terraform in `active-active` mode, repeat the steps for each node in the installation. + + +## Post installation tasks + +Complete the following tasks after the initial installation. + +### Review startup checks + +When you start Terraform Enterprise, several startup checks also run to prevent errors related to invalid configurations or certificates, as well as other issues that could prevent the application from running successfully or safely. Refer to the [startup checks reference](/terraform/enterprise/deploy/reference/startup-checks) for additional information. + +### Create the initial admin user + +[Provision your first administrative user](/terraform/enterprise/deploy/initial-admin-user) and start using Terraform Enterprise. + +### Manage Docker containers + +We recommend using Docker's native lifecycle management to automatically restart Terraform Enterprise containers that fail due to transient network or infrastructure issues. You can manage Docker container lifecycles using Docker's restart policy. Refer to the [Docker documentation](https://docs.docker.com/config/containers/start-containers-automatically/#use-a-restart-policy) for details. + +### Manage the Docker service + +You can use `systemd` to automatically run `docker compose` when the system starts up. Managing the Docker Compose lifecycle is outside the scope of these instructions, but we provide the following example for managing Docker Compose on your Linux host for your convenience. + +Store the following configuration as `/etc/systemd/system/terraform-enterprise.service`: + +```ini +[Unit] +Description=Terraform Enterprise Service +Requires=docker.service +After=docker.service network.target + +[Service] +Type=oneshot +RemainAfterExit=yes +WorkingDirectory=/etc/terraform-enterprise +ExecStart=/usr/local/bin/docker compose up -d +ExecStop=/usr/local/bin/docker compose down +TimeoutStartSec=0 + +[Install] +WantedBy=multi-user.target +``` + +Run the following command to enable the service: + +```shell-session +$ systemctl enable --now terraform-enterprise +``` + +### Route requests to Terraform Enterprise public hostname + +You can direct requests sent to Terraform Enterprise's fully qualified domain name to the instance's internal IP address. This is useful for cloud environments where HTTP clients running on instances behind a load balancer cannot send requests to the public hostname of that load balancer. + +Add the `TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS` variable to your deployment configuration file and specify a comma-separated list of additional hosts to send requests to. Format each item in the list as `HOST:IP`. The IP must be a routable address for the instance where Terraform Enterprise is running. + +The following example sends requests to the fully-qualified domain name ``: + +```yaml +name: terraform-enterprise +services: + tfe: + image: images.releases.hashicorp.com/hashicorp/terraform-enterprise: + environment: + TFE_HOSTNAME: "terraform.example.com" + TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS: "terraform.example.com:" +``` + +This configuration injects `/etc/hosts` entries into the ephemeral Docker containers used to launch the underlying `terraform` binary. Refer to the [`TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS` reference](/terraform/enterprise/deploy/reference/configuration#tfe_run_pipeline_docker_extra_hosts) for additional information. + +## Example deployment configurations + +You can copy one of the following example configurations and modify the values to per your environment. Refer to [Configuration Reference](/terraform/enterprise/deploy/reference/configuration) +for a list of all configuration options. + +Refer to the [Docker Compose documentation](https://docs.docker.com/compose/) +for details on installing, configuring, and running Docker Compose. + +### Example `disk` mode configuration + +The following compose configuration deploys Terraform Enterprise in `disk` mode using a bind +mount to make the disk path used for Terraform Enterprise data storage available. The path you specify as the source of the bind mount must exist on the instance running Terraform Enterprise. This path must be backed by durable +storage as provided by your cloud provider, such as Elastic Block Storage for AWS. + +```yaml +# Caution: $ is a reserved character in docker compose files for variable interpolation and can be escaped by using $$. +# https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/ +--- +name: terraform-enterprise +services: + tfe: + image: images.releases.hashicorp.com/hashicorp/terraform-enterprise: + environment: + TFE_LICENSE: "" + TFE_HOSTNAME: "" + TFE_ENCRYPTION_PASSWORD: '' + TFE_OPERATIONAL_MODE: "disk" + TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache" + TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem" + TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem" + TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/bundle.pem" + TFE_IACT_SUBNETS: "" + cap_add: + - IPC_LOCK + read_only: true + tmpfs: + - /tmp:mode=01777 + - /run + - /var/log/terraform-enterprise + ports: + - "80:80" + - "443:443" + volumes: + - type: bind + source: /var/run/docker.sock + target: /run/docker.sock + - type: bind + source: ./certs + target: /etc/ssl/private/terraform-enterprise + - type: bind + source: + target: /var/lib/terraform-enterprise + - type: volume + source: terraform-enterprise-cache + target: /var/cache/tfe-task-worker/terraform +volumes: + terraform-enterprise-cache: +``` + +### Example `external` mode configuration + +The following compose configuration deploys Terraform Enterprise in `external` mode and expects to connect to an external PostgreSQL server and an external S3-compatible object storage server. + +```yaml +# Caution: $ is a reserved character in docker compose files for variable interpolation and can be escaped by using $$. +# https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/ +--- +name: terraform-enterprise +services: + tfe: + image: images.releases.hashicorp.com/hashicorp/terraform-enterprise: + environment: + TFE_LICENSE: "" + TFE_HOSTNAME: "" + TFE_ENCRYPTION_PASSWORD: '' + TFE_OPERATIONAL_MODE: "external" + TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache" + TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem" + TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem" + TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/bundle.pem" + TFE_IACT_SUBNETS: "" + + # Database settings. See the configuration reference for more settings. + TFE_DATABASE_USER: "" + TFE_DATABASE_PASSWORD: '' + TFE_DATABASE_HOST: "" + TFE_DATABASE_NAME: "" + TFE_DATABASE_PARAMETERS: "" + + # Object storage settings. See the configuration reference for more settings. + TFE_OBJECT_STORAGE_TYPE: "s3" + TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: "" + TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: '' + TFE_OBJECT_STORAGE_S3_REGION: "" + TFE_OBJECT_STORAGE_S3_BUCKET: "" + cap_add: + - IPC_LOCK + read_only: true + tmpfs: + - /tmp:mode=01777 + - /run + - /var/log/terraform-enterprise + ports: + - "80:80" + - "443:443" + volumes: + - type: bind + source: /var/run/docker.sock + target: /run/docker.sock + - type: bind + source: ./certs + target: /etc/ssl/private/terraform-enterprise + - type: volume + source: terraform-enterprise-cache + target: /var/cache/tfe-task-worker/terraform +volumes: + terraform-enterprise-cache: +``` + +### Example `active-active` mode configuration + +The following compose configuration deploys Terraform Enterprise in `active-active` mode and expects to connect to an external PostgreSQL server, external S3-compatible object storage server, and external Redis-compatible caching server. + +```yaml +# Caution: $ is a reserved character in docker compose files for variable interpolation and can be escaped by using $$. +# https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/ +--- +name: terraform-enterprise +services: + tfe: + image: images.releases.hashicorp.com/hashicorp/terraform-enterprise: + environment: + TFE_LICENSE: "" + TFE_HOSTNAME: "" + TFE_ENCRYPTION_PASSWORD: '' + TFE_OPERATIONAL_MODE: "active-active" + TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache" + TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem" + TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem" + TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/bundle.pem" + TFE_IACT_SUBNETS: "" + + # Database settings. See the configuration reference for more settings. + TFE_DATABASE_USER: "" + TFE_DATABASE_PASSWORD: '' + TFE_DATABASE_HOST: "" + TFE_DATABASE_NAME: "" + TFE_DATABASE_PARAMETERS: "" + + # Object storage settings. See the configuration reference for more settings. + TFE_OBJECT_STORAGE_TYPE: "s3" + TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: "" + TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: "" + TFE_OBJECT_STORAGE_S3_REGION: "" + TFE_OBJECT_STORAGE_S3_BUCKET: "" + + # Redis settings. See the configuration reference for more settings. + TFE_REDIS_HOST: "" + TFE_REDIS_USER: "" + TFE_REDIS_PASSWORD: "" + TFE_REDIS_USE_TLS: "" + TFE_REDIS_USE_AUTH: "" + + # Vault cluster settings. + # If you are using the default internal vault, this should be the private routable IP address of the node itself. + TFE_VAULT_CLUSTER_ADDRESS: "https://:8201" + cap_add: + - IPC_LOCK + read_only: true + tmpfs: + - /tmp:mode=01777 + - /run + - /var/log/terraform-enterprise + ports: + - "80:80" + - "443:443" + - "8201:8201" + volumes: + - type: bind + source: /var/run/docker.sock + target: /run/docker.sock + - type: bind + source: ./certs + target: /etc/ssl/private/terraform-enterprise + - type: volume + source: terraform-enterprise-cache + target: /var/cache/tfe-task-worker/terraform +volumes: + terraform-enterprise-cache: +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/docker/scale.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/docker/scale.mdx new file mode 100644 index 0000000000..8a5823ebaf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/docker/scale.mdx @@ -0,0 +1,141 @@ +--- +page_title: Scale Terraform Enterprise instances hosted on Docker +description: >- + Learn how to migrate Terraform Enterprise instances hosted on Docker to `active-active` mode so that you can scale your deployment. +--- + +# Scale Terraform Enterprise instances hosted on Docker + +This topic describes how to migrate Terraform Enterprise instances hosted on Docker to `active-active` mode so that you can scale your deployment. + +## Introduction + +When your organization requires increased reliability or performance from Terraform Enterprise that your current single application instance cannot provide, we recommend switching to `active-active` mode. In this mode, Terraform Enterprise connects to external systems that store and manage application and state data. + +Operating Terraform Enterprise in `active-active` mode improves application scalability, but it also increases operational complexity. Consider the following aspects of operating Terraform Enterprise in `active-active` mode: + +- Observability concerns when monitoring multiple instances +- Custom automation required to manage the lifecycle of application nodes +- [CLI-based commands](/terraform/enterprise/deploy/reference/cli) for administration + +-> **Note**: Contact your Customer Success Manager before attempting to follow this guide. They can walk you through the process and make it as seamless as possible. + +## Prerequisite + +The primary requirement for `active-active` is an auto-scaling group or equivalent with a single instance running Terraform Enterprise. This auto-scaling group (ASG) should be behind a load balancer, and you can expose it to the public Internet, depending on your requirements. + +As mentioned earlier, your Terraform Enterprise application installation should be completely automated to ensure the auto-scaling group can scale down to zero and back up to one without human intervention. + +-> **Note**: Operating Terraform Enterprise in `active-active` mode on VMware infrastructure requires configuring a load balancer to route traffic across Terraform Enterprise servers. This documentation does not cover that setup. While auto-scaling groups are unavailable via native vCenter options, you must still configure a fully automated deployment. You must also reduce the available servers to one for upgrades, maintenance, and support. + +Your Terraform Enterprise application must be configured to run in [`external` operational mode](/terraform/enterprise/deploy/reference/configuration#external) to connect to an external PostgreSQL database and object storage. + +## Step 1: Prepare to Externalize Redis + +Prior to reconfiguring Terraform Enterprise, Redis must be externalized. Redis is used for background work scheduling across multiple nodes in an `active-active` installation. + +### Prepare Network + +There are new access requirements involving ingress and egress: + +- **Port 6379** (or the port the external Redis uses) must be open between the nodes and the Redis service. +- **Port 8201** must be open between the nodes to allow Vault to run in [High Availability](/vault/docs/internals/high-availability) mode. + +### Provision Redis + +Externalizing Redis allows multiple active application nodes. Terraform Enterprise installs as a standard product on VMware machines and validated to work with the native Redis services from AWS, Azure, and GCP. +The Redis deployment must satify the [requirements](/terraform/enterprise/deploy/configuration/storage/connect-redis#requirements) of Terraform Enterprise. + +Refer to the [cloud-specific configuration guides for more details](#redis-server). + +## Step 2: Update your Configuration File Templates + +Before installing, you must change the templates for the configuration files mentioned in the [prerequisites](#prerequisite). + +### Update Application Settings + +Your existing Terraform Enterprise application settings are still necessary, but must be expanded. Refer to [Configuration Reference](/terraform/enterprise/deploy/reference/configuration) for a full list of configuration options. + +#### Enable `active-active` mode + +Update the Terraform Enterprise configuration to reflect the `active-active` operational mode: + +| **Key** | **Required Value** | **Specific Format Required** | +| -------------------- | ------------------ | ---------------------------- | +| `TFE_OPERATIONAL_MODE` | `active-active` | **Yes**, string. | + +#### Configure External Redis + +You must also expand your Terraform Enterprise application settings to support an external Redis instance: + +| **Key** | **Required Value** | **Specific Format Required** | +| ---------------------| ------------------------------------------------------------------------- | ---------------------------- | +| TFE_REDIS_HOST | Hostname in `host:port` format of an external Redis instance. | **Yes**, string. | +| TFE_REDIS_USE_AUTH\* | Set to `true`, if you are using a Redis service that requires a password. | **Yes**, boolean. | +| TFE_REDIS_USER\* | User used to authenticate to Redis. | **Yes**, string. | +| TFE_REDIS_PASSWORD\* | User used to authenticate to Redis. | **Yes**, string. | +| TFE_REDIS_USE_TLS\* | Set to `true` if you are using a Redis service that requires TLS. | **Yes**, boolean. | + +_\* Fields marked with an asterisk are only necessary if your particular external Redis instance requires them._ + +To use in-transit encryption with GCP Memorystore for Redis, you must [download the CA certificate](https://cloud.google.com/memorystore/docs/redis/enabling-in-transit-encryption#downloading_the_certificate_authority) for your Redis instance and configure it within the `ca_certs` Terraform Enterprise application setting. Additionally, ensure to configure the `redis_port` and `redis_use_tls` settings correctly. + +#### Add Encryption Password + +Add the encryption password value to your configuration. The password must be identical between node instances for the `active-active` architecture to function: + +| **Key** | **Description** | **Value can change between deployments?** | **Specific Format Required** | +| ------------ | ----------------------------------------- | --------------------------------------------------------------- | ---------------------------- | +| `TFE_ENCRYPTION_PASSWORD` | Used to encrypt sensitive data | **No.** Changing makes decrypting existing data impossible. | No | + + +## Step 3: Connect to External Redis + +Once you are prepared to include the modified configuration options in your configuration files, you must connect a single node to your newly provisioned Redis service by rebuilding your node instance with the new settings. + +### Re-provision Terraform Enterprise Instance + +Terminate the existing instance by scaling down to zero. Once terminated, you can scale back up to one instance using your revised configuration. + +### Wait for Terraform Enterprise to Install + +It can take up to 15 minutes for the node to provision and install the Terraform Enterprise application. You can monitor the provisioning status by watching your auto scaling group in your cloud’s web console. To confirm the successful implementation of the Terraform Enterprise application you can use the `tfectl` CLI tool in the Terraform Enterprise container to monitor the application status: + +```bash +tfectl app status +``` + +Refer to the [CLI reference](/terraform/enterprise/deploy/reference/cli) for more status and troubleshooting commands. + +### Validate Application + +With installation complete, it is time to validate the new Redis connection. Terraform Enterprise uses Redis both as a cache for API requests and a queue for long running jobs (e.g., Terraform runs). Test the queue for long running jobs by running real Terraform operations through the system. + +Once you are satisfied the application is running as expected, you can move on to step 4 to scale up to two nodes. + +## Step 4: Scale to Two Nodes + +You can now safely change the number of instances in your auto scaling group (or equivalent) to two. + +### Scale Down to Zero Nodes + +Scale down to zero nodes to fully disable the admin dashboard. Wait until the the existing instance is terminated. + +### Scale Up to Two Nodes + +Now that you have tested your external Redis connection change the min and max instance count of your Auto Scaling Group to two nodes. + +### Wait for Terraform Enterprise to Install + +You need to wait up to 15 minutes for the application to respond as healthy on both nodes. Monitor the status of the install [using the same methods](#validate-application). + +Note that you must check each node _independently_. + +### Validate Application + +Finally, confirm the application is functioning as expected when running multiple nodes by running Terraform plans and applying them through the system (and any other tests specific to your environment). + +Confirm the general functionality of the Terraform Enterprise user interface to validate [the tokens you added in Step 2 are set correctly](#step-2-update-your-configuration-file-templates). Browse the `Run` interface and your organization's private registry to confirm your application functions as expected. + + +@include "replicated-and-fdo/admin/active-active-scaling-partial.mdx" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/index.mdx new file mode 100644 index 0000000000..7ce55d96a4 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/index.mdx @@ -0,0 +1,59 @@ +--- +page_title: Terraform Enterprise deployment overview +description: Terraform Enterprise offers flexible deployment options for container runtime environments and data management modes. Learn about the deployment process. +--- + +# Terraform Enterprise deployment overview + +This topic provides an overview of the Terraform Enterprise deployment process. For information about deploying Terraform Enterprise using the Replicated platform, refer to [Deploy Terraform Enterprise to Replicated](/terraform/enterprise/deploy/replicated). If your existing Terraform Enterprise instances were deployed to Replicated, [refer to our migration guide](/terraform/enterprise/deploy/replicated-migration) for instructions on how to deploy the platform to one of the supported runtimes. + +## Introduction + +Terraform Enterprise runs in containerized instances that support flexible deployment options for self-hosted environments. You can deploy Terraform Enterprise to the following non-Replicated runtimes: + +- Docker +- Kubernetes +- OpenShift +- Nomad +- Podman + +You can configure Terraform Enterprise to run as a self-contained application that manages the associated data storage or as an integrated installation that connects to externally-managed data storage systems. Refer to [Data storage overview](/terraform/enterprise/deploy/configuration/storage) for additional information. + +## Terraform module workflow + +HashiCorp provides the following Terraform modules in the public Terraform registry to help you deploy Terraform Enterprise: + +- [Amazon Web Services EC2](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-hvd/aws/latest) +- [Amazon Web Services EKS](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-eks-hvd/aws/latest) +- [Microsoft Azure VM](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-hvd/azurerm/latest) +- [Microsoft Azure AKS](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-aks-hvd/azurerm/latest) +- [Google Cloud GCE](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-hvd/google/latest) +- [Google Cloud GKE](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-gke-hvd/google/latest) + +Each official module above aligns with HashiCorp Validated Designs, HashiCorp's official recommendations based on extensive experience working with various organizations to deploy our solutions. To learn more about using HashiCorp Validated Designs, contact your account team. + +## Manual workflow + +Terraform Enterprise supports several container runtime environments and operating modes for managing data that provide you with flexible deployment options. To deploy Terraform Enterprise, create a configuration file that specifies your deployment settings, complete any external prerequisites associated with your deployment configuration, then use your runtime interface to run the installation. + +### Prepare the deployment environment + +Create a host instance on your cloud provider and install a runtime environment. You must also configure network access, assign a DNS hostname, and install the TLS certificate. If you intend to connect Terraform Enterprise to an external Vault server or PostgreSQL database, you must also configure and launch those systems. Refer to [Prepare the Terraform Enterprise host environment](/terraform/enterprise/deploy/prepare-host/) for details. + +### Create the configuration + +Create a deployment configuration file for your runtime environment, such as a values.yaml if you are deploying to Kubernetes or a compose.yaml file if you are deploying to Docker, and specify the Terraform Enterprise configurations. The runtime platform starts the Linux container for Terraform Enterprise according to the settings defined in the configuration file. Refer to [Create deployment configuration overview](/terraform/enterprise/deploy/configuration/) for additional information. + +### Install Terraform Enterprise + +After completing the prerequisites, deploy Terraform Enterprise to your runtime environment. Refer to the following topics for instructions: + +- [Deploy Terraform Enterprise to Docker](/terraform/enterprise/deploy/docker) +- [Deploy Terraform Enterprise to Kubernetes](/terraform/enterprise/deploy/kubernetes) +- [Deploy Terraform Enterprise to OpenShift](/terraform/enterprise/deploy/openshift) +- [Deploy Terraform Enterprise to Podman](/terraform/enterprise/deploy/podman) +- [Deploy Terraform Enterprise to Nomad](/terraform/enterprise/deploy/nomad) + +### Review startup checks + +When you start Terraform Enterprise, several startup checks also run to prevent errors related to invalid configurations or certificates, as well as other issues that could prevent the application from running successfully or safely. Refer to the [startup checks reference](/terraform/enterprise/deploy/reference/startup-checks) for additional information. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/initial-admin-user.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/initial-admin-user.mdx new file mode 100644 index 0000000000..90c34c8d33 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/initial-admin-user.mdx @@ -0,0 +1,115 @@ +--- +page_title: Create the initial admin user for Terraform Enterprise +description: >- + You must create an admin user to manage Terraform Enterprise and run workloads. Learn how to create the initial admin user in Terraform Enterprise. +--- + +# Create initial Terraform Enterprise admin user + +This topic describes how to create the initial admin user for managing the Terraform Enterprise application and run workloads. Create the initial admin user after installing Terraform Enterprise. Refer to [Deploy Terraform Enterprise](/terraform/enterprise/deploy) for additional information about the deployment process. + +## Overview + +Complete the following steps to create the initial admin user: + +1. **Retrieve the initial admin creation token**: The initial admin creation token (IACT) is available for a limited time after starting Terraform Enterprise. You must present the token to authenticate your request to create an admin user. +1. **Create initial admin user**: You can create the initial admin user in two ways: using the browser or directly from the container or pod. + +## Requirements + +Terraform Enteprise must not have any other users in the system when creating an admin user by presenting the IACT. + +## Retrieve initial admin creation token + +You may set the initial admin creation token in [`TFE_IACT_TOKEN` setting reference](/terraform/enterprise/deploy/reference/configuration#tfe_iact_token) if desired. If it is set, you may proceed to [Create initial admin user](#create-initial-admin-user). + +If this value is not set, a random token will be generated. By default, you have 60 minutes to retrieve the IACT upon start up. Refer to the [`TFE_IACT_TIME_LIMIT` setting reference](/terraform/enterprise/deploy/reference/configuration#tfe_iact_time_limit) for additional information about changing the time limit. + +You can retrieve the IACT from the Terraform Enterprise UI or from the Terraform Enterprise container or pod. + +### UI + +Navigate to `https://${TFE_HOSTNAME}/admin/retrieve-iact` in your browser on a workstation to retrieve your token. The host name is one of the addresses specified in the [`TFE_IACT_SUBNETS` setting](/terraform/enterprise/deploy/reference/configuration#tfe_iact_subnets). + + +### Container or pod + +You can retrieve your IACT token directly from the Terraform Enterprise container or pod: + + + + +Run the following command to retrieve your IACT token from a Kubernetes pod. +```shell-session +$ kubectl exec -it -n -- tfectl admin token +``` + + + + +Run the following command to retrieve your IACT token from a Docker container. +```shell-session +$ docker exec tfectl admin token +``` + + + + +Run the following command to retrieve your IACT token from a Podman container. +```shell-session +$ podman exec -it tfectl admin token +``` + + + + + +Run the following command to retrieve your IACT token from a Nomad allocation. +```shell-session +$ nomad alloc exec -namespace= -it -task tfectl admin token +``` + + + +## Create initial admin user + +You can create the initial admin user in the Terraform Enterprise UI or by sending a `POST` request to the `/admin/initial-admin-user` API endpoint. + +### UI + +1. Navigate to `https://${TFE_HOSTNAME}/admin/account/new?token=${IACT_TOKEN}` in your browser on a workstation. The host name is one of the addresses specified in the [`TFE_IACT_SUBNETS` setting](/terraform/enterprise/deploy/reference/configuration#tfe_iact_subnets). +1. When prompted, complete the steps to create the admin user. + +### Container or pod + +1. Create a JSON document with the username, email address, and password for the admin user you want to create. Refer to [`initial-admin-user` reference documentation](/terraform/enterprise/api-docs/admin/initial-admin-user) for additional information. + + The following example payload creates a user named `manage`: + + ```json + { + "username": "manage", + "email": "it@mycompany.com", + "password": "thisisabadpassword" + } + ``` + +1. Send a `POST` request to the `/admin/initial-admin-user` endpoint. You must present the IACT token. Refer to [Retrieve initial admin creation token](#retrieve-initial-admin-creation-token) for instructions. + + The following example sends the initial admin user details in a file called `payload.json`: + ```shell + curl \ + --header "Content-Type: application/json" \ + --request POST \ + --data @payload.json \ + https://${TFE_HOSTNAME}/admin/initial-admin-user?token=${IACT_TOKEN} + ``` + +The API returns a `created` status response: + +```json +{ + "status": "created", + "token": "aabbccdd.v1.atlas.ddeeffgghhiijjkkllmmnnooppqqrrssttuuvvxxyyzz" +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/index.mdx new file mode 100644 index 0000000000..b8817d1e4a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/index.mdx @@ -0,0 +1,342 @@ +--- +page_title: Deploy Terraform Enterprise to Kubernetes +description: >- + Learn how to deploy Terraform Enterprise to Kubernetes-orchestrated containers using Helm. +--- + +# Deploy Terraform Enterprise to Kubernetes + +This topic describes how to deploy Terraform Enterprise to Kubernetes. You should have a deep understanding of Kubernetes before deploying Terraform Enterprise to a production Kubernetes environment. + +## Overview + +You should deploy external service dependencies outside the Kubernetes cluster and scale reliably to accommodate Terraform Enterprise workloads. The following diagram shows the Terraform Enterprise architecture when deployed to Kubernetes-orchestrated containers: + +![Example of Kubernetes Architecture](/img/docs/TFE_In_Kubernetes.png) + +Complete the following steps to install Terraform Enterprise: + +1. Complete the prerequisites. +1. Install the Helm chart and apply your override values. +1. Complete post installation tasks. + +Complete post installation tasks, such creating the initial admin user account. + +## Prerequisites + +Complete the following tasks before attempting to install Terraform Enterprise. + +### Prepare the deployment environment + +Provide a DNS hostname for Terraform Enterprise and the associated TLS certificate. Additionally, you must configure your network so that your host can receive and send traffic. Refer to [Prepare the host environment](/terraform/enterprise/deploy/prepare-host) for details about preparing the host environment. + +### Deploy external storage systems + +Deploy the database and other storage devices so that Terraform can connect to them when the application starts. Refer to [Data storage settings overview](/terraform/enterprise/deploy/configuration/storage) for additional information. + +### Create the deployment configuration + +Create a custom YAML configuration file, for example `/tmp/overrides.yaml`, to override the default values in the Terraform Enterprise Helm chart. The file contains settings for the operational mode, license, TLS certificates, and network configuration. Add any additional configurations necessary for your environment. Refer to [Configuration file overview](/terraform/enterprise/deploy/configuration/) for additional information. + +@include 'common-kubernetes-blocks/externalizing-secret-values.mdx' + +#### Automatic environment configuration + +There are a collection of environment variables that are predetermined or computed when using the Terraform Enterprise Helm chart. When you configure the variables as `.Values.env.variables` entries, Terraform Enterprise overwrites them with the predetermined or computed values. Refer to [the config-map.yaml template](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/templates/config-map.yaml) for version of the chart that you are using. + +#### Running as non-root + +By default, Terraform Enterprise runs as the `terraform-enterprise` user. If you want to enforce Terraform Enterprise as a non-root user, you must set the Helm chart values: + +* `.securityContext.runAsNonRoot: true` +* `.securityContext.runAsUser: 1000` +* `.securityContext.fsGroup: 1012`. + +## Install Terraform Enterprise with Helm + +1. Connect to the host instance. + +1. Log in to the Terraform Enterprise container image registry. + + ```shell-session + $ cat | docker login --username terraform images.releases.hashicorp.com --password-stdin + ``` + +1. Pull the Terraform Enterprise image from the registry. + + ```shell-session + $ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + +1. Create a custom namespace. + + ```shell-session + $ kubectl create namespace + ``` + +1. Create an image pull secret in `` to fetch the `terraform-enterprise` container from the ``. This URL can be `images.releases.hashicorp.com`, or your internal container registry. If you are using `images.releases.hashicorp.com`, use `terraform` as the `` parameter in the following command with `--docker-password=$(cat /path/to/terraform.hclic)` + + ```shell-session + $ kubectl create secret docker-registry terraform-enterprise --docker-server= --docker-username= --docker-password= -n + ``` + +1. Add the Hashicorp Helm registry: + + ```shell-session + $ helm repo add hashicorp https://helm.releases.hashicorp.com + ``` + +1. Render the `terraform-enterprise` chart with your custom [values file](https://helm.sh/docs/chart_template_guide/values_files/) ``, for example `tmp/overrides.yaml`. + + ```shell-session + $ helm template terraform-enterprise hashicorp/terraform-enterprise –n --values + ``` + +1. Install `terraform-enterprise`, this step can take several minutes. + + ```shell-session + $ helm install terraform-enterprise hashicorp/terraform-enterprise –n --values + ``` + +1. Inspect `terraform-enterprise` pods to verify their successful start. + + ```shell-session + $ kubectl get pods -n + ``` + + If Terraform Enterprise pods fail to start, refer to [Kubernetes Troubleshooting](/terraform/enterprise/deploy/troubleshoot/error-messages#kubernetes). + +1. By default, Terraform Enterprise installs a load balancer service. Retrieve the external IP address of this service. + + ```shell-session + $ kubectl get services -n + ``` + +1. Set up a DNS record that points to your external IP address to enable routing to your ``. A DNS address is required to communicate with Terraform Enterprise, and it is managed outside of Kubernetes and the Terraform Enterprise helm chart or application. + +1. Validate the readiness of the Terraform Enterprise application by querying the health check endpoint. + + ```shell-session + $ curl https://tfe.test.hashicorp.com/_health_check + ``` + +## Post installation tasks + +Complete the following tasks after the initial installation. + +### Review startup checks + +When you start Terraform Enterprise, several startup checks also run to prevent errors related to invalid configurations or certificates, as well as other issues that could prevent the application from running successfully or safely. Refer to the [startup checks reference](/terraform/enterprise/deploy/reference/startup-checks) for additional information. + +### Create initial admin user + +[Provision your first administrative user](/terraform/enterprise/deploy/initial-admin-user) and start using Terraform Enterprise. + +### Configure the security context + +Modify the `.securityContext` Helm chart value to set the pod security configuration. Modify the `.container.securityContext` Helm chart value to set the container security configuration. You must also omit the `allowPrivilegeEscalation` container security context option or set it to `true`. + +### Create a custom Helm chart fork + +The [Terraform Enterprise Helm Chart](https://github.com/hashicorp/terraform-enterprise-helm) is designed to meet the needs of the majority of our users. You can fork our Helm chart and adapt it to your organization’s requirements. + +If you contact HashiCorp support, include your custom helm chart alongside your support bundle to ensure support has all the information they need. + +### Custom ingress +You can define an optional ingress resource using the ingress controller. Refer the [Terraform Enterprise Helm Chart](https://github.com/hashicorp/terraform-enterprise-helm) documentation for additional information about the controller. + +Specify values for the ingress section in the deployment configuration. Refer to the example values file in the [Terraform Enterprise Helm chart repository](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/docs/example/terraform-enterprise-prereqs/values.yaml#L46C9-L46C9) for a demonstration of how to enable ingress configuration. + +Complete the following steps to set up an custom ingress configuration with Nginx: +1. Install the [nginx controller](https://kubernetes.github.io/ingress-nginx/deploy/) in a different namespace. +1. Deploy Terraform Enterprise with Ingress configured in your values file. +1. Get the address from the ingress resource like so: + +```shell-session +$ kubectl get ingress +NAME CLASS HOSTS ADDRESS PORTS AGE +terraform-enterprise nginx 80, 443 60s +``` + +## Example configurations + +The following examples for each cloud-platform are based on cloud native hosted PostgreSQL, storage, or Redis cache services. You can copy an example configuration and modify the values to per your environment. Refer to [Configuration Reference](/terraform/enterprise/deploy/reference/configuration) +for a list of all configuration options. + +The examples also depend on the following conditions: + +- Values under `.env.variables` are set as a `ConfigMap` and mounted as Terraform Enterprise environment variables. +- Values under `.env.secrets` are set as Kubernetes secrets and mounted as Terraform Enterprise environment variables. +- Extend the `env.configMapRefs[]` or `env.secretRefs[]` with your own resources to add additional `ConfigMap` or `Secret` resources within your environment configuration. + +- Values marked `BASE_64_ENCODED*` indicate that the value given must be base 64 encoded. If you are using this certificate configuration to host Terraform Enterprise web traffic, this value must be valid with the `env.TFE_HOSTNAME`, or match the wildcard pattern. + + +### AWS Elastic Kubernetes Service (EKS) + +```YAML +replicaCount: +tls: + certData: + keyData: + caCertData: +image: + repository: images.releases.hashicorp.com + name: hashicorp/terraform-enterprise + tag: +env: + variables: + TFE_HOSTNAME: + TFE_IACT_SUBNETS: + + # Database settings. + TFE_DATABASE_HOST: + TFE_DATABASE_NAME: + TFE_DATABASE_PARAMETERS: + TFE_DATABASE_USER: + + # Redis settings. + TFE_REDIS_HOST: + TFE_REDIS_USE_TLS: + TFE_REDIS_USE_AUTH: + TFE_REDIS_USER: + + # S3 settings. For Server Side Encryption settings, see to the configuration reference. + TFE_OBJECT_STORAGE_TYPE: s3 + TFE_OBJECT_STORAGE_S3_BUCKET: + TFE_OBJECT_STORAGE_S3_REGION: + TFE_OBJECT_STORAGE_S3_USE_INSTANCE_PROFILE: + secrets: + TFE_DATABASE_PASSWORD: '' + TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: + TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: '' + TFE_REDIS_PASSWORD: '' + TFE_LICENSE: + TFE_ENCRYPTION_PASSWORD: '' +``` + +### Google Kubernetes Engine (GKE) + +```YAML +replicaCount: +tls: + certData: + keyData: + caCertData: +image: + repository: images.releases.hashicorp.com + name: hashicorp/terraform-enterprise + tag: +env: + variables: + TFE_HOSTNAME: + TFE_IACT_SUBNETS: + + # Database settings. + TFE_DATABASE_HOST: + TFE_DATABASE_NAME: + TFE_DATABASE_PARAMETERS: + TFE_DATABASE_USER: + + # Redis settings. + TFE_REDIS_HOST: + TFE_REDIS_USE_TLS: + TFE_REDIS_USE_AUTH: + TFE_REDIS_USER: + + # Google Cloud Storage settings. + TFE_OBJECT_STORAGE_TYPE: google + TFE_OBJECT_STORAGE_GOOGLE_BUCKET: + TFE_OBJECT_STORAGE_GOOGLE_PROJECT: + secrets: + TFE_DATABASE_PASSWORD: '' + TFE_OBJECT_STORAGE_GOOGLE_CREDENTIALS: + TFE_REDIS_PASSWORD: '' + TFE_LICENSE: + TFE_ENCRYPTION_PASSWORD: '' +``` + +### Azure Kubernetes Service (AKS) + + +```YAML +replicaCount: +tls: + certData: + keyData: + caCertData: +image: + repository: images.releases.hashicorp.com + name: hashicorp/terraform-enterprise + tag: +env: + variables: + TFE_HOSTNAME: + TFE_IACT_SUBNETS: + + # Database settings. + TFE_DATABASE_HOST: + TFE_DATABASE_NAME: + TFE_DATABASE_PARAMETERS: + TFE_DATABASE_USER: + + # Redis settings. + TFE_REDIS_HOST: + TFE_REDIS_USE_TLS: + TFE_REDIS_USE_AUTH: + TFE_REDIS_USER: + + # Azure container storage settings. + TFE_OBJECT_STORAGE_TYPE: azure + TFE_OBJECT_STORAGE_AZURE_ACCOUNT_NAME: + TFE_OBJECT_STORAGE_AZURE_CONTAINER: + TFE_OBJECT_STORAGE_AZURE_ENDPOINT: + secrets: + TFE_DATABASE_PASSWORD: '' + TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY: '' + TFE_REDIS_PASSWORD: '' + TFE_LICENSE: + TFE_ENCRYPTION_PASSWORD: '' +``` + +#### Using AKS with Workload Identity + +If you are using AKS with Workload Identity, the configuration is slightly different. You must set omit the `TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY` secret, and configure +the AKS cluster as an OIDC provider. + +```yaml +serviceAccount: + enabled: true + name: "" + annotations: + azure.workload.identity/client-id: "" + labels: + azure.workload.identity/use: "true" +pod: + labels: + azure.workload.identity/use: "true" +agents: + rbac: + enabled: true +``` + +The `` is the client_id from the Azure User Assigned Identity. One can find this value in the Azure portal. + +This user assigned identity needs a federated identity credential with the following subject format +`"system:serviceaccount:${KUBERNETES_NAMESPACE}:${SERVICE_ACCOUNT_NAME}"`. + +The issuer of the federated identity should be the cluster's issuer URL. One can retrieve this URL by running the following command: + +```shell-session +$ az aks show --resource-group --name --query "oidcIssuerProfile.issuerUrl" --output tsv +``` + +## Terraform modules for managed-kubernetes + +HashiCorp provides the following Terraform modules in the public Terraform registry to help you deploy Terraform Enterprise on EKS, GKE and AKS: + +- [Amazon Web Services EKS](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-eks-hvd/aws/latest) +- [Google Cloud GKE](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-gke-hvd/google/latest) +- [Microsoft Azure AKS](https://registry.terraform.io/modules/hashicorp/terraform-enterprise-aks-hvd/azurerm/latest) + +Each official module above aligns with HashiCorp Validated Designs, HashiCorp's official recommendations based on extensive experience working with various organizations to deploy our solutions. To learn more about using HashiCorp Validated Designs, contact your account team. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/index.mdx new file mode 100644 index 0000000000..f71f747dde --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/index.mdx @@ -0,0 +1,23 @@ +--- +page_title: Scale Terraform Enterprise instances on Kubernetes +description: >- + Learn how to increase the number of replica instances of your Terraform Enterprise deployment on Kubernetes to scale up Terraform activities. +--- + +# Scale Terraform Enterprise instances on Kubernetes + +This topic provides overview information about scaling your Terraform Enterprise deployment to meet demand. + +## Workflows + +To handle increased computational workload requirements of your organization, you can scale Terraform Enterprise horizontally by increasing the number of `terraform-enterprise` pods and `terraform-enterprise agent` pods. Refer to [Increase number of replica instances](/terraform/enterprise/deploy/kubernetes/scale/replicas) for instructions. + +You can also increase run capacity to reduce run queue lengths and shorten wait time for runs to begin execution. Refer to [Increase run capacity](/terraform/enterprise/deploy/kubernetes/scale/run-capacity) for instructions. + +## Impact on external resources + +Scaling your deployment up to meet larger demands may impact the following external resources. + +- **PostgreSQL**: In our testing, CPU utilization and memory usage increased when scaling Terraform Enterprise pods with increasing capacity concurrency. We recommend closely monitoring both CPU utilization and memory usage and provide additional resources as necessary. +- **Redis**: In our testing, Redis CPU or memory spiked in some cases. You should monitor your Redis server and provide additional resources as necessary. + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/replicas.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/replicas.mdx new file mode 100644 index 0000000000..c6525d189a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/replicas.mdx @@ -0,0 +1,96 @@ +--- +page_title: Increase number of replica instances +description: >- + Learn how to increase the number of replica instances of your Terraform Enterprise deployment on Kubernetes. +--- + +# Increase number of replica instances + +This topic describes how to increase the number of replica instances of your Terraform Enterprise deployment on Kubernetes so that your deployment can scale to meet demand. + +## Introduction + +To handle increased computational workload requirements of your organization, you can scale Terraform Enterprise horizontally by increasing the number of `terraform-enterprise` pods and `terraform-enterprise agent` pods. Refer to the [Scale Terraform Enterprise instances on Kubernetes overview](/terraform/enterprise/deploy/kubernetes/scale) for additional information. + +## Requirements + +The requirements for your Kubernetes cluster depend on the specific workloads. Update CPU, RAM, storage, and network capacity according to your applications demands. + +### CPU requirements + +The following minimum requirements for a Terraform Enterprise pod are appropriate for most initial production deployments and for development and test environments: + +| CPU | Memory | +| ------- | ---------| +| 2 core | 3 GB RAM | + +We tested with a minimum memory of 2.5GB and 0.75 vCPU and scaled up to maximum of 7.5GB and 4 vCPU. + +```YAML +resources: + requests: + memory: "2500Mi" + cpu: "750m" + limits: + memory: "7500Mi" + cpu: "4000m" +``` + +### Database requirements + +The following table describes the recommended minimum memory and CPU requirements for the PostgreSQL database. You may require additional resources depending on the anticipated demands on Terraform Enterprise within your organization: + +| Type | CPU | Memory | Storage | +| ------- | -------|-----------|---------| +| Minimum | 4 core | 16 GB RAM | 50 GB | +| Scaling | 8 core | 32 GB RAM | 50 GB | + + +### Redis cache requirements + +We successfully tested Terraform Enterprise with the following data store configuration: + +- 6GB Redis cache. +- Multi-AZ enabled. +- Automated failover enabled. + + +## Increase `terraform-enterprise` pods + +Kubernetes creates a _`Deployment`_ object that manages the `terraform-enterprise` pods through a _`ReplicaSet`_. Refer to the Kubernetes documentation to learn about [`Deployment`s](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) and [`ReplicaSet`s](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/). + +The [`deployment.yaml`](https://github.com/hashicorp/terraform-enterprise-helm/blob/0e1a2eb6644bdf6b710c9ce97ed1d2b8e3c558ae/templates/deployment.yaml#L13) file generated during the Terraform Enterprise deployment process includes the `replicas` field, which determines how many `terraform-enterprise` pods Kubernetes should create. + +```YAML +apiVersion: apps/v1 +kind: Deployment +metadata: + name: terraform-enterprise + labels: + app: terraform-enterprise +spec: + replicas: {{ .Values.replicaCount }} + selector: + matchLabels: + app: terraform-enterprise + template: + metadata: + annotations: + {{- if .Values.pod.annotations }} + {{ toYaml .Values.pod.annotations | indent 8 }} + {{ end }} + labels: + app: terraform-enterprise +``` + +Complete the following steps to increase the number of `terraform-enterprise` pods for your deployment: + +1. Update the value of `replicaCount` in the [values file](https://github.com/hashicorp/terraform-enterprise-helm/blob/0e1a2eb6644bdf6b710c9ce97ed1d2b8e3c558ae/values.yaml#L8) of your Helm chart. The `replicaCount` value maps to the `spec.replicas` value in the deployment file. The maximum number of `terraform-enterprise` pods you can instruct Kuberneteds to create is `5`. +1. Run the `helm upgrade` command to update the deployment. + +In the following example, the `replicaCount` is set to `3`, which sets the `spec.replicas` value to `3` after running `helm ugrade`: + +```YAML + replicaCount: 3 + ... +``` \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/run-capacity.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/run-capacity.mdx new file mode 100644 index 0000000000..0e37c62e2c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/kubernetes/scale/run-capacity.mdx @@ -0,0 +1,99 @@ +--- +page_title: Increase Terraform Enterprise run capacity on Kubernetes +description: >- + Learn how to increase the run capacity when operating Terraform Enterprise on Kubernetes. +--- + +# Increase Terraform Enterprise run capacity + +This topic describes how to increase the run capacity of your Terraform Enterprise deployment on Kubernetes. For instructions on how to create the number of replicas, refer to [Increase number of replicas](/terraform/enterprise/deploy/kubernetes/scale/replicas). + +## Introduction + +Terraform Enterprise executes runs by creating agent jobs in a different namespace, which in turn creates agent pods. Each run executes in its own agent pod. When run finishes, Terraform automatically cleanse up the agent job and agent pod. You can increase the maximum number of concurrent agent pods to reduce run queue lengths and wait time for runs to begin execution. + +Complete the following steps to increase run capacity: + +- Configure the maximum number of concurrent agent jobs. +- Configure memory and CPU limits for individual pods. +- Adjust the Kubernetes worker timeout settings to allow Kubernetes to automatically scale the cluster. + +## Configure concurrency + +To increase the number of agent pods that Terraform Enterpise can run concurrently, update the `TFE_CAPACITY_CONCURRENCY` value on the values file on the Helm chart and run `helm upgrade` to update the deployment. + +The `TFE_CAPACITY_CONCURRENCY` value sets the maximum number of agent jobs each Terraform Enterprise pod can create at a given time in the `TFE_CAPACITY_CONCURRENCY` setting. The default concurrency is set to `10`. You can specify up to `50` agent jobs. The following example sets the concurrent number of agent jobs allowed to `11`: + +``` YAML + env: + ... + variables: + TFE_CAPACITY_CONCURRENCY: "11" +``` + +`TFE_CAPACITY_CONCURRENCY` applies to each `terraform-enterprise` pod. For example, if you have three `terraform-enterprise` pods, and `TFE_CAPACITY_CONCURRENCY` is `10`, the maximum number of agent pods for Terraform Enterprise is `30`. Refer to [`TFE_CAPACITY_CONCURRENCY`](/terraform/enterprise/deploy/configuration#tfe_capacity_concurrency) for additional information. + +## Configure limits for individual agent pods + +You can increase the maximum amount of memory and CPU for each agent pod in the `TFE_CAPACITY_MEMORY`and `TFE_CAPACITY_CPU` values and run `helm upgrade` to update the deployment. Refer to the [Helm chart](https://github.com/hashicorp/terraform-enterprise-helm/blob/0e1a2eb6644bdf6b710c9ce97ed1d2b8e3c558ae/values.yaml#L167-L169) for additional information. + +In the following example, the CPU limit is set to `0`, which enables an unlimited about of CPU. The memory limit is set to `2048`, which enables up to 2048 mebibytes. + +``` YAML + env: + ... + variables: + TFE_CAPACITY_CONCURRENCY: "10" # Set the maximum number of concurrent runs, eg: 10 + TFE_CAPACITY_CPU: "0" # Set the maximum CPU utilization. "0" equals unlimited. + TFE_CAPACITY_MEMORY: "2048" # Set the maximum memory utilization, eg: "2048" equals 2048Mi. +``` + +## Use Kubernetes cluster autoscaling + + +Enable the `autoscaling` setting for your Kubernetes cluster so that Kubernetes can automatically scale the node capacity when Kubernetes cannot schedule the run due to resource constraints. You must also adjust the [`TFE_RUN_PIPELINE_KUBERNETES_WORKER_TIMEOUT`](/terraform/enterprise/deploy/reference/configuration#tfe_run_pipeline_kubernetes_worker_timeout) setting so that Terraform Enterprise does not timeout before the Kubernetes environment can scale to meet resource demand for additional runs. This setting should be set to be greater than the number of seconds Kubernetes requires to scale out and initiate a new node fitting the constraints and requirements for the agent jobs that Terraform Enterprise generates. + +When `autoscaling` is enabled for the Kubernetes cluster, Terraform Enterprise still complies with the maximum number of jobs it can run concurrently per the `TFE_CAPACITY_CONCURRENCY` configuration. We recommend that you carefully configure your Kubernetes environment with infrastructure layer upper and lower bounds on node availability to meet your business needs outside of Terraform Enterprise. + +### Google Cloud Platform Kubernetes Engine with Autopilot + +You can use Google Cloud Platform Kubernetes Engine (GKE) pod annotations to fine tune the stability and availability of Terraform Enterprise. GKE Autopilot is a mode of operation that manages clusters. Refer to the [Autopilot documentation](https://cloud.google.com/kubernetes-engine/docs/concepts/autopilot-overview) for additional information. + +At a minimum, we recommend the following annotations and node selectors: + +- require that `tfc-agent` pods are not interruptable using the following annotation: `cluster-autoscaler.kubernetes.io/safe-to-evict=false` +- select a balanced compute class for both Terraform Enterprise pods and `tfc-agent` workloads using the following node selector: `cloud.google.com/compute-class: "Balanced"` +- set resource requests for CPU and memory for Terraform Enterprise and `tfc-agent` pods + +Manage these settings in the [Terraform Enterprise Helm chart values](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/values.yaml). + +The following example shows how to configure features significant to operating Terraform Enterprise in GKE Autopilot. Note that the example is incomplete and does not include additional configurations for operating Terraform Enterprise: + +```yaml +# Terraform Enterprise resource requests, annotations, and node selectors +resources: + requests: + memory: "8000Mi" + cpu: "8" +nodeSelector: + cloud.google.com/compute-class: "Balanced" +pod: + annotations: + cluster-autoscaler.kubernetes.io/safe-to-evict: "false" + +# Agent resource requests, annotations, and node selectors, utilizing the agent pod template feature +agentWorkerPodTemplate : + metadata : + annotations : + "cluster-autoscaler.kubernetes.io/safe-to-evict": "false" + spec : + nodeSelector : + cloud.google.com/compute-class: "Balanced" + containers: + - name: "tfc-agent" + image: "hashicorp/tfc-agent:1.17.5" + resources : + requests : + memory: 2Gi + cpu: 2 +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/access-cli.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/access-cli.mdx new file mode 100644 index 0000000000..f3b236ca2e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/access-cli.mdx @@ -0,0 +1,50 @@ +--- +page_title: Access the Terraform Enterprise CLI +description: >- + The Terraform Enterprise CLI lets you reconfigure Terraform Enterprise, stop the application safely, and produce support bundles. Learn how to access the CLI. +--- + +# Access the Terraform Enterprise CLI + +Terraform Enterprise provides a command line interface that enables you to change its configuration, stop the application safely, and produce support bundles. Refer to [CLI reference](/terraform/enterprise/deploy/reference/cli) for information about the commands available. + +## Docker + +To connect to the Docker container hosting Terraform Enterprise, execute the following command from the server where Terraform Enterprise is running. If you have named your container something other than `terraform-enterprise` please replace that with your container name. + +```bash +$ docker exec -it terraform-enterprise bash +``` + +## Kubernetes + +Complete the following steps to connect to the Kubernetes pod hosting Terraform Enterprise: + +1. Authenticate to the Kubernetes cluster by executing the relevant command. + + + + ```bash + $ az aks get-credentials --resource-group --name + ``` + + ```bash + $ aws eks --region update-kubeconfig --name + ``` + + ```bash + $ gcloud container clusters get-credentials --project= + ``` + + +1. Retrieve the pod name by executing the following command. + + ```bash + $ kubectl get pods -n + ``` + +1. Execute the following command to remote into the pod. + + ```bash + $ kubectl exec -n -it -- bash + ``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/backup-restore.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/backup-restore.mdx new file mode 100644 index 0000000000..0f1e6f9773 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/backup-restore.mdx @@ -0,0 +1,180 @@ +--- +page_title: Back up and restore Terraform Enterprise +description: >- + Use Terraform Enterprise's back up and restore APIs for disaster recovery. +--- + +# Back up and restore Terraform Enterprise + +Terraform Enterprise provides an API to back up and restore all of its application data. + +The backup and restore API is separate from the Terraform Enterprise application-level APIs. As such, a separate authorization token is required to use the backup and restore API. See [Authentication](#authentication) below for more details. + +Using the backup and restore API is the only supported way to migrate between a deployment with an external Vault and one with the internal Vault service. + +> **Note**: We do not recommend using the backup and restore API to maintain periodic Terraform Enterprise application data backups. For best practices, refer to our recommended patterns covering the [backup](/terraform/tutorials/recommended-patterns/pattern-backups) and [restore](/terraform/tutorials/recommended-patterns/pattern-recovery) processes. + +## About backups and restores + +The backup and restore API backs up all of the data stored in a Terraform Enterprise installation, including both the blob storage and the PostgreSQL database. It does not back up the installation configuration. This backup can then be restored to a new installation of Terraform Enterprise. + +Please note the following when using the backup and restore API: + +- The version of Terraform Enterprise cannot be changed between a backup and restore. That is, a backup taken from one version of Terraform Enterprise cannot be restored to an installation running a different version of Terraform Enterprise. +- The version of PostgreSQL being used cannot be changed between a backup and restore. That is, a backup taken from a Terraform Enterprise installation using one version of PostgreSQL cannot be restored to an installation using a different version of PostgreSQL. +- The Terraform Enterprise installation that will be restored to must be a new, running installation with no existing application data. +- Once a restore is completed, the Terraform Enterprise application will need to be restarted before it can use the restored data. + +See also: + +- [Data Security](/terraform/enterprise/deploy/reference/data-security) for details about the contents of Terraform Enterprise's blob storage and PostgreSQL database. + +### Authentication + +The backup and restore API uses a separate authorization token which can be found within the Terraform Enterprise Docker container. + +```shell-session +$ docker exec -t terraform-enterprise-tfe-1 /bin/bash -c 'cat /var/run/terraform-enterprise/backup-restore/config.hcl | grep backup_token' +``` + +-> **Note:** This authorization token is specific to the Terraform Enterprise installation. As a result, the authorization token used to create a backup may be different than the authorization token used to perform a restore. Please ensure you are using the correct authorization token when performing a backup or restore operation. + +The backup and restore API is separate from the Terraform Enterprise application-level APIs and cannot be accessed with Terraform Enterprise user, team, or organization API tokens. + +To use this authorization token with the backup and restore API, pass the `Authorization: Bearer ` header in your API requests. + +~> **Important:** Since this authorization token can access all of the data in a Terraform Enterprise installation, protect it very carefully. + +### Security and encryption + +Terraform Enterprise uses HashiCorp Vault to encrypt and decrypt its data. The Vault encryption keys that are used to encrypt and decrypt this data are not preserved during a backup or restore. Instead, during a backup, the data is decrypted by Vault and then re-encrypted using a password provided by you, resulting in an encrypted backup blob. During a restore, the same password that you provided during the backup must be used to decrypt the data before it is re-encrypted with the new Terraform Enterprise installation's Vault encryption keys. + +The backup and restore API expect this password to be provided as a JSON object with a `password` property within the request payload. The value for the `password` property can be any valid string. Here's what an example JSON object looks like. + +```json +{ + "password": "befit-brakeman-footstep-unclasp" +} +``` + +~> **Important:** The same password that was provided during backup must be provided during restore. This password can be used to access all of the data that was backed up. Please protect it very carefully. + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +## Creating a backup + +`POST /_backup/api/v1/backup` + +To initiate a backup, make a POST request to the backup endpoint on a running Terraform Enterprise installation. + +The response to this request will be an encrypted binary blob containing all of your Terraform Enterprise data. When using this endpoint, please: + +- Remember to specify an output file for the encrypted backup blob. +- Be prepared to download and store many gigabytes of data to the filesystem of whichever machine the request is sent from. For best performance and to avoid disconnections, we recommend sending this request from a server colocated with the Terraform Enterprise installation rather than from a workstation. +- Treat this encrypted backup blob as sensitive data and ensure it is stored securely. +- Remember the password that was used to encrypt this backup blob. + +| Status | Response | Reason | +| ------- | ------------------ | ----------------------------- | +| [200][] | Binary backup blob | Successfully created a backup | +| [400][] | (none) | Invalid request | +| [500][] | (none) | Internal server error | + +~> **Important:** A successful backup **must** return `200`. If `200` is not returned and the call silently closes, the backup blob may be incomplete, resulting in data loss. + +### Request body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------- | ------ | ------- | ---------------------------------------------------------- | +| `password` | string | | The password used to encrypt the backup blob. | +| `skip_object_storage` | bool | `false` | Whether or not to skip backing up the object storage data. | + +### Sample payload + +```json +{ + "password": "befit-brakeman-footstep-unclasp" +} +``` + +### Sample request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --request POST \ + --data @payload.json \ + --output backup.blob \ + https:///_backup/api/v1/backup +``` + +## Restoring a backup + +`POST /_backup/api/v1/restore` + +Before restoring, you must first create a new Terraform Enterprise installation. + +-> **Note:** The authorization token used to restore the backup is specific to the Terraform Enterprise installation. If restoring to a separate Terraform Enterprise installation, the authorization token will be different for the restore than it was for the backup. See [Authentication](#authentication) above for more details. + +Once the Terraform Enterprise application is up and running, you can initiate a restore by making a POST request to the restore endpoint. + +Be prepared to upload many gigabytes of data from the filesystem of whichever machine the request is sent from. For best performance and to avoid disconnections, we recommend sending this request from a server colocated with the Terraform Enterprise installation rather than from a workstation. + +| Status | Response | Reason | +| ------- | -------- | ------------------------------ | +| [200][] | (none) | Successfully restored a backup | +| [400][] | (none) | Invalid request | +| [500][] | (none) | Internal server error | + +### Request body + +This POST endpoint requires the following form fields which must be provided as `multipart/form-data`. + +| Form field | Description | +| ---------- | ---------------------------------------------------------------------------------- | +| `snapshot` | An encrypted backup blob downloaded from the Terraform Enterprise backup endpoint. | +| `config` | A JSON file containing a JSON object. See the table below. | + +The JSON file used in the `config` form field above must contain a JSON object with the following properties. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------- | ------ | ------- | --------------------------------------------- | +| `password` | string | | The password used to decrypt the backup blob. | + +### Sample payload + +```json +{ + "password": "befit-brakeman-footstep-unclasp" +} +``` + +### Sample request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --request POST \ + --form config=@payload.json \ + --form snapshot=@backup.blob \ + https:///_backup/api/v1/restore +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/failover.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/failover.mdx new file mode 100644 index 0000000000..176988e5b1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/failover.mdx @@ -0,0 +1,85 @@ +--- +page_title: PostgreSQL database failover +description: Learn how implementing automatic failover for your Terraform Enterprise database and a high-availability (HA) PostgreSQL database cluster improves resilience and reduces data loss in the event of a failure. +--- + +# PostgreSQL database failover + +This topic provides an overview of the PostgreSQL database failover process and associated concepts to help you understand how failover works in Terraform Enterprise. This information is only relevant when operating Terraform Enterprise in `active-active` or `external` mode and when Terraform Enterprise is connected to an external database cluster. Refer to [Database connection overview](/terraform/enterprise/deploy/configuration/storage/connect-database) for additional information. + +## Introduction + +Configuring your Terraform Enterprise deployment to connect to a PostgreSQL database replica ensures continuous database availability when Terraform Enterprise is unable to reach the primary database. To enable failover, configure Terraform Enterprise to reconnect when a failover event occurs. Additionally, you must configure your monitoring tool or PostgreSQL software to detect failures that trigger failover operations. + +Refer to [Connect to a PostgreSQL cluster](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres-cluster) for instructions. + +For additional guidance, refer to the following example scenarios: + +- [Connect to a PostgreSQL cluster deployed to Patroni](/terraform/enterprise/deploy/configuration/storage/connect-database/patroni) +- [Connect to a PostgreSQL cluster deployed to Aurora](/terraform/enterprise/deploy/configuration/storage/connect-database/aurora) + +## Failover event stages + +The following stages describe the lifecycle of a failover event. + +### Failure detection + +Continuous health checks monitor the primary database node for signs of failure, such as connectivity issues or system crashes. When a health check fails, the monitoring tool reports that the primary node is unavailable. This involves checking predefined health metrics and thresholds to confirm the node’s failure status. + +### Failover operations + +You should deploy an external monitoring tool that is able to promote the most up-to-date standby node to the primary node during a failover event. The tool should also enable the node to handle read and write operations. + +This step may involve manually updating load balancers or connection strings used by applications. Terraform Enterprise notifies applications and clients connected to the database the change either through automatic reconfiguration or by using tools that support failover transitions. + +### Resolution + +After addressing the cause of the failure, you can restore the failed primary node and then demote the standby node. Update the primary node with data it was unable to store while it was unavailable and direct it to rejoin the cluster. + + +## Failover metrics + +Recovery point objective (RPO) and recovery time objective (RTO) are metrics that define the resilience of your system. These metrics help you understand and plan your disaster recovery and data protection strategies. + +### RPO + +RPO refers to the maximum acceptable amount of data loss measured in time. It describes how much data you can afford to lose in the event of a failure. For example, an RPO of 10 minutes means that, in the worst case, up to 10 minutes of data could be lost due to a failure. + +Achieving a low RPO requires frequent data replication and backups, which ensures that data is consistently synchronized across primary and replica nodes. In PostgreSQL, the [replication method](#replication) and the frequency of backups directly affect the RPO. + +The synchronous replication method results in lower RPO because it ensures that the database commits transactions to both the primary and replica nodes simultaneously. But using synchronous replication may impact performance. Asynchronous replication can provide better database performance but result in a higher RPO. Note that RPO is a function of the database configuration and unrelated to Terraform Enterprise performance. + +### RTO + +RTO refers to the maximum acceptable amount of time to restore normal operations after a failure. It describes how quickly you recover from a failure. An RTO of 15 minutes, for instance, indicates that the system must be fully operational within 15 minutes of a failure. + +In a highly-available (HA) PostgreSQL architecture, automated failover processes, efficient database recovery mechanisms, and robust monitoring tools that quickly detect and address issues can help you achieve a low RTO. The complexity of the HA topology, the effectiveness of failover mechanisms, and the speed at which data can be restored all contribute to the RTO. + +## High availability + +In order to implement a failover strategy, your Terraform Enterprise deployment must connect to a high-availability or highly-available (HA) PostgreSQL cluster. An HA PostgreSQL cluster ensures that the database remains operational and accessible during failures. For technical details, refer to the PostgreSQL [documentation](https://www.postgresql.org/docs/current/high-availability.html) on high-availability + +### Architecture of a PostgreSQL cluster + +A common HA cluster architecture has the following components: + +- **Primary node**: The database server where write operations occur. It handles both read and write requests but focuses primarily on write transactions. +- **Standby nodes**: These are replicas of the primary node. They receive updates from the primary node and can serve read-only queries to balance the load. +- **Load balancer**: This component distributes incoming connections across the primary and standby nodes. The load balancer ensures that no single node becomes a bottleneck and to manage failovers seamlessly. +- **Failover manager**: A system or tool that monitors the health of nodes and orchestrates the failover process if the primary node fails. + +### Replication +Replication refers to copying data from the primary node to standby nodes to ensure data redundancy and availability. Streaming replication refers to when the primary node sends a continuous stream of write-ahead logs (WAL) to standby nodes. The standby nodes then apply these logs to stay synchronized with the primary database. You can specify one of the following replication types in the `synchronous_commit` setting of your PostgreSQL configuration: + +- `asynchronous`: PostgreSQL commits transactions on the primary node without waiting for the standby nodes to acknowledge. This offers better performance but increases the risk of data loss. +- `synchronous`: PostgreSQL does not commit transactions until at least one standby node has acknowledged receipt. This reduces the risk of data loss but can impact write performance due to the added latency. + +Replication lag in `asynchronous` mode refers to the delay between when PostgreSQL commits a transaction on the primary node and when the commit is replicated to the standby nodes. This lag can impact data consistency during failover. Minimizing replication lag is crucial for ensuring that standby nodes are as up-to-date as possible with the primary node’s state. + +## Next steps + +Refer to the following topics for guidance on implementing failover for your Terraform Enterprise deployment: + +- [Connect to a PostgreSQL cluster](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres-cluster) for instructions. +- [Connect to a PostgreSQL cluster deployed to Patroni](/terraform/enterprise/deploy/configuration/storage/connect-database/patroni) +- [Connect to a PostgreSQL cluster deployed to Aurora](/terraform/enterprise/deploy/configuration/storage/connect-database/aurora) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/index.mdx new file mode 100644 index 0000000000..20abed3f03 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/index.mdx @@ -0,0 +1,20 @@ +--- +page_title: Manage Terraform Enterprise deployment overview +description: Learn about Terraform Enterprise deployment management procedures, including monitoring, backing up, and upgrading your Terraform Enterprise installation. +--- + +# Manage Terraform Enterprise deployment overview + +This topic provides overview information about managing Terraform Enterprise deployed to non-Replicated runtimes. For information about managing Replicated deployments, refer to [Manage Terraform Enterprise on Replicated overview](/terraform/enterprise/deploy/replicated/manage). + +## Deployment management tasks + +You can perform the following deployment management tasks: + +- Connect to the Terraform Enterprise admin CLI. Refer to [Access the Terraform Enterprise command line](/terraform/enterprise/deploy/manage/access-cli) for instructions. +- Create and restore backups of the data stored by Terraform Enterprise. Refer to [Backup and restore](/terraform/enterprise/deploy/manage/backup-restore) for instructions. +- Upgrade to a new version of Terraform Enterprise. Refer to [Upgrade Terraform Enterprise](/terraform/enterprise/deploy/manage/upgrade) for instructions. +- Enable Terraform Enterprise observability features to ensure that your deployment operates as expected. Refer to [Monitor Terraform Enterprise](/terraform/enterprise/deploy/manage/monitor) for instructions. +- Configure your deployment to automatically send license consumption data to HashiCorp. This streamlines your license reporting processes. Refer to [Enable automated license reports](/terraform/enterprise/deploy/manage/license-report) for instructions. +- Configure your deployment to automatically send product usage data to HashiCorp. This streamlines your license reporting processes. Refer to [Enable automated product usage reports](/terraform/enterprise/deploy/manage/product-report) for instructions. + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/license-report.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/license-report.mdx new file mode 100644 index 0000000000..af5dc805e3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/license-report.mdx @@ -0,0 +1,83 @@ +--- +page_title: Enable automated license utilization reports +description: >- + License utilization reports provide insights about consumption to help you manage your budget. Learn how to enable automated license utilization reports. +--- + +# Enable automated license utilization reporting + +This topic describes how to enable Terraform Enterprise to automatically report license usage information to HashiCorp. Refer to [Terraform Enterprise license data reference](/terraform/enterprise/deploy/reference/license-data) for information about the license data Terraform Enterprise sends to HashiCorp. + +## Introduction + +License usage reports provide the following benefits: + +- Insight into how much more you can deploy under your current contract. +- Protection against over-utilization. +- Predictable consumption for budgeting purposes. + +Additionally, you can review license usage with your existing monitoring solutions, such as Splunk and Datadog. Monitoring license consumption enables you to optimize and manage your deployments. Refer to [Monitor Terraform Enterprise](/terraform/enterprise/deploy/manage/monitor) for instructions on how to enable log forwarding for non-Replicated runtimes. Refer to documentation for [enabling log forwarding for Replicated deployments](/terraform/enterprise/deploy/replicated/monitoring/logging) if Terraform is deployed to Replicated. + +## Requirements + +- Configure your network to allow outbound HTTPS traffic on port `443`. +- Configure your network to allow HTTPS egress on port `443` from `https://reporting.hashicorp.services` by allow-listing the following IP addresses: + + - `100.20.70.12` + - `35.166.5.22` + - `23.95.85.111` + - `44.215.244.1` + +- Configure your network to allow egress to `https://api.replicated.com` + +Refer to [Configure network access](/terraform/enterprise/deploy/configuration/network) for additional information. + +## Enable license reporting + +Terraform is configured to automatically report license usage data by default. When enabled, Terraform sends HashiCorp the minimum data required to validate license usage as defined in our contracts in order to guide you through data insights and improve product value, experience, and quality. Refer to [Opt out of license utilization reporting](#opt-out-of-license-utilization-reporting) for instructions on how to disable automatic reports. + + +## Check logs + +Terraform Enterprise automatically begins reporting license utilization data within approximately 24 hours from start up. Refer to [Log location and format](/terraform/enterprise/deploy/manage/monitor#log-location-and-format) to verify that the data sent successfully. + +```json +{ + "@level": "debug", + "@message": "export finished successfully", + "@module": "tfe-licensing.licensingexporter", + "@timestamp": "2023-05-10T17:48:06.656979Z" +} +``` + +If your installation is air-gapped or your network does not allow the correct egress, logs show the following error: + +```json +{ + "@level": "error", + "@message": "error exporting snapshot", + "@module": "tfe-licensing.census", + "@timestamp": "2023-05-11T01:50:51.662155Z", + "err": "export failed with error POST https://reporting.hashicorp.services giving up after 5 attempt(s): Post \"https://reporting.hashicorp.services\": dial tcp 35.166.5.222:443: i/o timeout" +} +``` + +In this case, reconfigure your network to allow egress and check back in roughly 24 hours. + +## Opt out of license utilization reporting + +If your installation is air-gapped or you want to manually collect and report on the same license utilization metrics, you can opt-out of automated reporting. Note that you are still required to manually collect and send license utilization metrics to HashiCorp, even when you opt out of sending automated license usage reports. + +Before opting out, we strongly recommend reviewing the [license report reference](/terraform/enterprise/deploy/reference/license-data). Report any concerns related to the automatically-reported data to your account manager. + +1. Add the following environment variable to your deployment configuration `TFE_LICENSE_REPORTING_OPT_OUT=TRUE`. +1. Restart the application. +1. Check your product logs after approximately 24 hours to verify that the system is no longer attempting to send reports. + +### Check logs + +Automatic license utilization reporting will start sending data within roughly 24 hours. [Check the product logs](/terraform/enterprise/deploy/manage/monitor#enable-log-forwarding) for records that the data sent successfully. + +Terraform Enterprise logs report an error when your installation is air-gapped or when your network does not allow the correct egress. + + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/monitor.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/monitor.mdx new file mode 100644 index 0000000000..9507309a6e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/monitor.mdx @@ -0,0 +1,157 @@ +--- +page_title: Monitor Terraform Enterprise deployments +description: Learn how to enable logs and metrics to monitor your Terraform Enterprise installation's performance. +--- + +# Monitor Terraform Enterprise + +This topic describes how to enable logs and metrics in Terraform Enterprise so that you can monitor your non-Replicated deployment. For information about monitoring Replicated deployments, refer to [Terraform Enterprise Log Forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging) and [Monitoring a Terraform Enterprise Instance](/terraform/enterprise/deploy/replicated/monitoring/monitoring) in the Replicated administration section. + +## Overview + +Complete the following steps to monitor your Terraform Enterprise deployment: + +1. Enable log forwarding. Terraform Enterprise writes logs directly to standard output and standard error, which allows you to forward logs using native tooling for your deployment platform. +1. Enable metrics collection. Metrics collection is disabled by default. Update your deployment configuration file to enable metrics collection + +## Enable log forwarding + +Terraform Enterprise writes logs directly to standard output and standard error. This allows you to forward logs using native tooling for your deployment platform. +Terraform Enterprise logs directly to standard output and standard error. This +allows you to forward logs using native tooling for your deployment platform. + +### Log location and format + +The individual service logs are located within the +`/var/log/terraform-enterprise` directory inside the container. + +```sh +/var/log/terraform-enterprise +├── atlas.log +├── nginx.log +├── sidekiq.log +└── vault.log +``` + +Each service log is a plain text file containing the logs for that service. Logs +are collated and logged to the container's standard output in JSON format. Each +log entry contains two fields: + +* `component`: The name of the individual service that emitted the log entry. +* `log`: The contents of the log message. + +An example set of log entries emitted by a Terraform Enterprise container would appear as follows: + +```sh +{"log":"2023-09-18 02:39:05 [INFO] msg=Worker start worker=AuthenticationTokenDeletionWorker","component":"sidekiq"} +{"log":"2023-09-18T02:39:05.098Z pid=156 tid=2pos class=FailedJobWorker jid=1010d28ac591979d9decb61f INFO: start","component":"sidekiq"} +{"log":"2023-09-18 02:39:05 [INFO] msg=Worker start worker=FailedJobWorker","component":"sidekiq"} +{"log":"2023-09-18 02:39:05 [INFO] msg=Worker finish worker=AuthenticationTokenDeletionWorker","component":"sidekiq"} +{"log":"2023-09-18T02:39:05.114Z pid=156 tid=2pyc class=AuthenticationTokenDeletionWorker jid=515e8a727a3e4948e9dbb04a elapsed=0.034 INFO: done","component":"sidekiq"} +{"log":"2023-09-18 02:39:05 [INFO] agent_jobs_processed=[] agent_jobs_errored=[] msg=Worker finish worker=FailedJobWorker","component":"sidekiq"} +{"log":"2023-09-18T02:39:05.118Z pid=156 tid=2pos class=FailedJobWorker jid=1010d28ac591979d9decb61f queue=default elapsed=0.02 INFO: done","component":"sidekiq"} +{"log":"2023-09-18 02:39:13 [INFO] [3efaaec9-48d4-4517-9fde-127f80faacb4] [dd.service=atlas dd.trace_id=1904097642804464614 dd.span_id=0 ddsource=ruby] {\"method\":\"GET\",\"path\":\"/\",\"format\":\"html\",\"status\":301,\"allocations\":493,\"duration\":0.72,\"view\":0.0,\"db\":0.0,\"location\":\"https://tfe.example.com/session\",\"dd\":{\"trace_id\":\"1904097642804464614\",\"span_id\":\"0\",\"env\":\"\",\"service\":\"atlas\",\"version\":\"\"},\"ddsource\":[\"ruby\"],\"uuid\":\"3efaaec9-48d4-4517-9fde-127f80faacb4\",\"remote_ip\":\"1.2.3.4\",\"request_id\":\"3efaaec9-48d4-4517-9fde-127f80faacb4\",\"user_agent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36\",\"user\":null,\"auth_source\":null}","component":"atlas"} +{"log":"2023-09-18 02:39:13 [INFO] [3cb89cfa-7d7f-4aeb-9e60-2256b016a839] [dd.service=atlas dd.trace_id=4370203755142829190 dd.span_id=0 ddsource=ruby] {\"method\":\"GET\",\"path\":\"/session\",\"format\":\"html\",\"status\":200,\"allocations\":3895,\"duration\":7.3,\"view\":5.77,\"db\":0.59,\"dd\":{\"trace_id\":\"4370203755142829190\",\"span_id\":\"0\",\"env\":\"\",\"service\":\"atlas\",\"version\":\"\"},\"ddsource\":[\"ruby\"],\"uuid\":\"3cb89cfa-7d7f-4aeb-9e60-2256b016a839\",\"remote_ip\":\"1.2.3.4\",\"request_id\":\"3cb89cfa-7d7f-4aeb-9e60-2256b016a839\",\"user_agent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36\",\"user\":null,\"auth_source\":null}","component":"atlas"} +{"log":"1.2.3.4 - - [18/Sep/2023:02:39:13 +0000] \"GET / HTTP/1.1\" 301 117 \"-\" \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36\"","component":"nginx"} +{"log":"1.2.3.4 - - [18/Sep/2023:02:39:13 +0000] \"GET /session HTTP/1.1\" 200 1735 \"-\" \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36\"","component":"nginx"} +{"log":"Storing the encrypted Vault token in Redis","component":"vault"} +``` + +Note that the format of individual service logs is considered an internal implementation +detail and is subject to change at any release. + +### External log forwarding + +We strongly recommend using an external log forwarding solution that aligns with +your existing observability solutions. Depending on the deployment platform, +native or third-party solutions (e.g., host-level monitoring agents) may be an +appropriate solution for log aggregation and forwarding. Hashicorp does not provide +support for third-party log forwarding solutions. + +#### Docker + +Docker supports a multitude of logging drivers. See the [Docker logging +driver](https://docs.docker.com/config/containers/logging/configure/) list for what +options are available. + +#### Kubernetes + +Kubernetes supports several architectures for log-forwarding. See the +[Kubernetes logging architectures documentation](https://kubernetes.io/docs/concepts/cluster-administration/logging/#cluster-level-logging-architectures) +for what options are available. + +### Native log forwarding + +As a convenience to aid in migrating from legacy Replicated environments +to Flexible Deployments, Terraform Enterprise provides a mechanism to inject +FluentBit `[OUTPUT]` configuration directives. This allows Terraform Enterprise +to use FluentBit plugins to forward log data directly to a number of external +destinations. + +FluentBit configuration must be provided the Terraform Enterprise container in +a file mounted to the container. That is, the configuration value must point to +a _filesystem path_ on the Docker container where the FluentBit configuration is +located; the configuration must _not_ contain the actual configuration itself. +This means it is the responsibility of the Terraform Enterprise operator to mount the config +snippet to the Docker container. + +| **Key** | **Description** | **Specific Format Required** | +| ------------------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------- | +| TFE_LOG_FORWARDING_CONFIG_PATH | Filesystem path on the Terraform Enterprise container containing FluentBit `[OUTPUT]` configuration | **Yes**, string. | + + +Exposing FluentBit configuration to Terraform Enterprise operators is provided as a convenience to +facilitate migration Terraform Enterprise installations. Customers are encouraged +to migrate away from relying on injected FluentBit configuration, and provide their +own log forwarding and aggregation solution in their infrastructure. + + +#### Limitations + +The FluentBit solution provided in [legacy Replicated Terraform Enterprise deployments](/terraform/enterprise/deploy/replicated/monitoring/logging) +emitted log entries that contained additional metadata keys, such as hostname and +IP address. This allowed for additional observability value from log entries, as +operators could identify the source of log entries. Unlike Replicated deployments, +logs emitted by the FluentBit plugins made available in Terraform Enterprise +Flexible Deployments do not contain additional metadata attached to each log entry. +This is due to the isolated nature of the FluentBit process within the Terraform +Enterprise Docker container; by definition, processes within the Docker container +are not exposed to host-level details. + +Because of this, we strongly recommend using an external log forwarding solution +that aligns with your existing observability solutions. See [external log forwarding](#external-log-forwarding) +for further discussion. + +Additionally, note that built-in log forwarding is only available for Docker-deployed +Terraform Enterprise installations. Terraform Enterprise deployed on Kubernetes +does not support leveraging the built-in FluentBit. + +#### Supported external destinations + +You can only forward logs to one of the supported external destinations below. +Each supported external destination contains example configuration for convenience. + +@include "replicated-and-fdo/monitoring/logging/supported-destinations-partial.mdx" + +## Enable metrics collection + +Metrics collection is disabled by default. Set the `TFE_METRICS_ENABLE` variable to `true` in your runtime configuration. The metrics service is not supported in Kubernetes installations. Refer to the [configuration reference](/terraform/enterprise/deploy/reference/configuration) for additional details. + +### Access metrics + +Terraform Enterprise exposes metrics on a port separate from the application. This allows operators to use network access controls to restrict access to metrics data to authorized consumers, such as a Prometheus server. + +By default, metrics are exposed on the following ports: + +- `9090` for HTTP. +- `9091` for HTTPS. + +You can configure the ports by setting the `TFE_METRICS_HTTP_PORT` and `TFE_METRICS_HTTPS_PORT` environment variables. Refer to the [configuration reference](/terraform/enterprise/deploy/reference/configuration) for additional details. + +The HTTP and HTTPS ports serve metrics on the path `/metrics`. + +By default, requests to the /metrics endpoint will emit metrics in JSON format. Use the query parameter `?format=prometheus` to emit metrics in Prometheus format. + +When using Prometheus, we recommend using a scrape interval shorter than the expiration time of 15 seconds to ensure that Terraform Enterprise reports data points from short-lived processes. + +Refer to the [metrics reference](/terraform/enterprise/deploy/reference/metrics) for details about the metrics Terraform Enterprise emits. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/product-report.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/product-report.mdx new file mode 100644 index 0000000000..9a2ad3ad64 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/product-report.mdx @@ -0,0 +1,88 @@ +--- +page_title: Enable automated product usage reports +description: >- + Learn how to enable automated license utilization reports. +--- + +# Enable automated product usage reports + +This topic describes how to enable Terraform Enterprise to automatically report product usage information to HashiCorp. Refer to [Terraform Enterprise product data reference](/terraform/enterprise/deploy/reference/product-data) for information about the product usage data Terraform Enterprise sends to HashiCorp. + +## Introduction + +Product usage reports provide the following benefits: + +- Insight into how much more you can deploy under your current contract. +- Protection against over-utilization. +- Predictable consumption for budgeting purposes. + +Additionally, you can review usage with your existing monitoring solutions, such as Splunk and Datadog. Monitoring product usage enables you to optimize and manage your deployments. Refer to [Monitor Terraform Enterprise](/terraform/enterprise/deploy/manage/monitor) for instructions on how to enable log forwarding for non-Replicated runtimes. Refer to documentation for [enabling log forwarding for Replicated deployments](/terraform/enterprise/deploy/replicated/monitoring/logging) if Terraform is deployed to Replicated. + +## Requirements + +- Configure your network to allow outbound HTTPS traffic on port `443`. +- Configure your network to allow HTTPS egress on port `443` from `https://reporting.hashicorp.services` by allow-listing the following IP addresses: + + - `100.20.70.12` + - `35.166.5.22` + - `23.95.85.111` + - `44.215.244.1` + +- Configure your network to allow egress to `https://api.replicated.com` + +Refer to [Configure network access](/terraform/enterprise/deploy/configuration/network) for additional information. + +## Enable product usage reporting + +Terraform is configured to automatically report product usage data by default. Refer to [Opt out of product usage reporting](#opt-out-of-product-usage-reporting) for instructions on how to disable automatic reports. + +## Check logs + +Terraform Enterprise automatically begins reporting data within approximately 24 hours from start up. Refer to [Log location and format](/terraform/enterprise/deploy/manage/monitor#log-location-and-format) to verify that the data sent successfully. + +```json +{ + "@level": "debug", + "@message": "export finished successfully", + "@module": "tfe-licensing.licensingexporter", + "@timestamp": "2023-05-10T17:48:06.656979Z" +} +``` + +Terraform Enterprise logs report an error when your installation is air-gapped or when your network does not allow the correct egress: + +```json +{ + "@level": "error", + "@message": "error exporting snapshot", + "@module": "tfe-licensing.census", + "@timestamp": "2023-05-11T01:50:51.662155Z", + "err": "export failed with error POST https://reporting.hashicorp.services giving up after 5 attempt(s): Post \"https://reporting.hashicorp.services\": dial tcp 35.166.5.222:443: i/o timeout" +} +``` + +In this case, reconfigure your network to allow egress and check back in roughly 24 hours. + +## Opt out of product usage reporting + +If your installation is air-gapped or you do not want to report product utilization data to HashiCorp, you can opt out of reporting. + +1. Add the following environment variable to your deployment configuration `TFE_USAGE_REPORTING_OPT_OUT=TRUE`. +1. Restart your system. +1. Check your product logs roughly 24 hours after opting out to make sure that the system does not send reports. + +When opting out in an internet-connected environment, the report contains fields in the JSON output set to `0`. + +### Manually reporting product usage in air-gapped environments +To report product usage in air-gapped environments, you can leverage the following CLI command: + +``` +tfectl admin usage-report +``` + +When in `disk` operating mode, Terraform Enterprise generates the product usage report in the `/run/terraform-enterprise/usage-report` directory. + +When in `external` and `active-active` mode and on Kubernetes, Terraform Enterprise uploads the product usage report to the same object store bucket where Terraform state files are stored. +Each specific run of the admin `usage-report` command generates the product usage report in a new JSON file. + +To send product usage reports to HashiCorp, visit the [**Licensing utilization reporting** page](https://portal.cloud.hashicorp.com/license-utilization/reports/create) and use the upload form. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/upgrade.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/upgrade.mdx new file mode 100644 index 0000000000..d7679d18ef --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/manage/upgrade.mdx @@ -0,0 +1,100 @@ +--- +page_title: Upgrade Terraform Enterprise +description: Learn how to upgrade Terraform Enterprise using Docker Compose and Helm to run new versions on Nomad, Kubernetes, OpenShift, Podman, or Docker. +--- + +# Upgrade Terraform Enterprise + +This topic describes how to upgrade Terraform Enterprise installations on non-Replicated runtimes. For information about upgrading Replicated deployments, refer to [Upgrade Terraform Enterprise on Replicated](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades). + +## Introduction + +We recommend upgrading in a non-production environment first before upgrading the production instance of Terraform Enterprise. + +## Upgrade + +Complete the following steps to upgrade Terraform Enterprise: + +1. Back up your Terraform Enterprise data. Refer to [Backup and restore](/terraform/enterprise/deploy/manage/backup-restore) for instructions. + +1. Use the Terraform Enterprise CLI to stop any existing Terraform runs and prevent Terraform Enterprise from starting new operations. Refer to [Gracefully stop work on a node](/terraform/enterprise/deploy/reference/cli#gracefully-stop-work-on-a-node) for instructions. + +1. If your deployment is configured to run multiple `terraform-enterprise` nodes, scale down to a single node. You can run multiple nodes when Terraform Enterprise is in `active-active` mode. Refer to [Configure the operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) for additional information. + +1. Stop the Terraform Enterprise application. + + + + + For installs that use Docker Compose, use the following command: + + ```shell-session + $ docker compose down + ``` + + + + + For installs that use Helm charts, update the `values.yaml` file's `replicaCount`: + + ```yaml + replicaCount: 0 + ``` + + + + +1. Pull the new Terraform Enterprise image for a specific [release](/terraform/enterprise/releases): `images.releases.hashicorp.com/hashicorp/terraform-enterprise:vYYYYMM-#`. + + + + + For installs that use Docker Compose, update the `compose.yaml` with the appropriate image tag: + + ```yaml + name: terraform-enterprise + services: + tfe: + image: images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + + + + + For installs that use Helm charts, update the `values.yaml` with the appropriate image tag and `replicaCount`: + + ```yaml + replicaCount: 1 + image: + repository: images.releases.hashicorp.com + name: hashicorp/terraform-enterprise + tag: + ``` + + + + +1. Start the Terraform Enterprise application with the new image. + + + + + For installs that use Docker Compose, use the following command: + + ```shell-session + $ docker compose up --detach + ``` + + + + + For installs that use Helm charts, upgrade the helm release with the new values: + + ```shell-session + $ helm -n upgrade --values= terraform-enterprise hashicorp/terraform-enterprise + ``` + + + + +1. Repeat the process for the production instance of Terraform Enterprise. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/nomad.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/nomad.mdx new file mode 100644 index 0000000000..80154c88a9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/nomad.mdx @@ -0,0 +1,606 @@ +--- +page_title: Deploy Terraform Enterprise to HashiCorp Nomad +description: >- + Learn how to install Terraform Enterprise on Nomad. +--- + +# Deploy Terraform Enterprise to HashiCorp Nomad + +This topic describes how to deploy Terraform Enterprise to a HashiCorp Nomad cluster. + +Complete the following steps to deploy Terraform Enterprise to Nomad-orchestrated containers: + +1. Complete the prerequisites. +1. Parameterize the Terraform Enterprise license, host, and TLS encryption settings by adding Nomad variables to your job specifications. This enable you to use the same job specification with different configurations. Refer to [Job Specification](/nomad/docs/job-specification) in the Nomad documentation for additional information. +1. Add Terraform Enterprise environment variables to your Nomad job specification to configure Terraform behavior. Refer to the [Terraform Enterprise configuration reference](/terraform/enterprise/deploy/configuration) for additional information. +1. Create a Nomad job specification for operating the Terraform Enterprise agent. Refer to [Custom Worker Image](/terraform/enterprise/deploy/custom-image) for additional information about the Terraform Enterprise agent. +1. Run the Nomad command for pulling the Terraform Enterprise image and installing the binary. + +## Prerequisites + +You can deploy Terraform Enterprise on Nomad version v1.5.0 and newer. + +Complete the following prerequisites before installing Terraform Enterprise on [Nomad](/nomad). + +Refer to the [Nomad clusters on the cloud tutorial](/nomad/tutorials/cluster-setup/cluster-setup-overview) for instructions on how to setup a Nomad cluster. + +### Nomad requirements + +You must provide the following Nomad items. + +Please make sure you have the following environment variables set before running Nomad commands from CLI: + +```bash +export NOMAD_ADDR=http://:4646 +export NOMAD_TOKEN= +export NOMAD_CLIENT_CERT= +export NOMAD_CLIENT_KEY= +export NOMAD_CA_CERT= +``` + +You can read more about the Nomad environment variables [here](/nomad/docs/commands). + +### Prepare the host environment + +Provide a DNS hostname for Terraform Enterprise and the associated TLS certificate. Additionally, you must configure your network so that your host can receive and send traffic. Refer to [Prepare the host environment](/terraform/enterprise/deploy/prepare-host) for details about preparing the host environment. + +### Deploy external storage systems + +Deploy the database and other storage devices so that Terraform can connect to them when the application starts. Refer to [Data storage settings overview](/terraform/enterprise/deploy/storage) for additional information. + +Terraform Enterprise requires the following external services to be present and accessible from the Nomad cluster: + +1. A PostgreSQL database. Refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for additional information. +1. An S3-compatible storage service, such as AWS S3, Azure Cloud Storage, and Google Cloud Storage. Refer to [External Services Mode](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/operational-mode-requirements#external-services-mode) for additional information. +1. Redis version 6 or 7. Redis Cluster is not supported. + +### Create the deployment configuration + +Create a custom YAML configuration file, for example `/tmp/overrides.yaml`, to override the default values in the Terraform Enterprise Helm chart. The file contains settings for the operational mode, license, TLS certificates, and network configuration. Add any additional configurations necessary for your environment. Refer to [Configuration file overview](/terraform/enterprise/deploy/reference/configuration) for additional information. + +### Create an ACL policy + +Create a token that grants access to the namespace where the Terraform Enterprise agents will run. The Terraform Enterprise job must present the token to the Terraform Enterprise agent so that it can run the agent job that performs Terraform operations. Refer to the [Nomad ACL system fundamentals](https://developer.hashicorp.com/nomad/tutorials/access-control/access-control) tutorial for instructions on how to create ACL policies linked to tokens. + +Create a policy file named `terraform-enterprise-policy.hcl` with the following content, and apply it to the `terraform-enterprise` namespace so that Terraform Enterprise has permission to run and manage agent jobs. + +```hcl +namespace "tfe-agents" { + capabilities = [ + "submit-job", + "dispatch-job", + "list-jobs", + "read-job", + "read-logs" + ] +} +``` + +The following example applies the `terraform-enterprise-policy` policy to the `tfe-job-task` task within the `tfe-job-group` of the `tfe-job` job. + + ```shell-session + $ nomad acl policy apply \ + -namespace terraform-enterprise -job tfe-job \ + -group tfe-job-group -task tfe-job-task \ + terraform-enterprise-policy ./terraform-enterprise-policy.hcl + ``` +Refer to the [Nomad documentation](/nomad/docs/commands/acl/policy/apply) for additional information about applying ACL policies. + +### Enable a workload identity + +Enable a workload identity on the Nomad cluster so that Nomad can inject the Nomad ACL token. The workload identity passes the token using the `NOMAD_TOKEN` environment variable. Refer to [Workload Identity](/nomad/docs/concepts/workload-identity) for additional information. + +Terraform Enterprise does not use workload identities on Nomad v1.4 and older. Instead, you must pass the `NOMAD_TOKEN` directly in the Terraform Enterprise job specification. Refer to [Configure Terraform Enterprise Nomad job specification](/terraform/enterprise/deploy/nomad#configure-terraform-enterprise-nomad-job-specification) for additional information. + +### Create namespaces + +Create at least two separate Nomad namespaces to provide better isolation, security, and control over Nomad workloads. One namespace is for the Terraform Enterprise job and the second is for the Terraform Enterprise agent job. Refer to the [Namespaces tutorial](/nomad/tutorials/manage-clusters/namespaces) in the Nomad documentation for instructions on how to create a namespace. + +## Parameterize Terraform Enterprise settings + +Add the following variables to your Terraform Enterprise Nomad job: + +- `tfe_license`: Specifies the Terraform Enterprise license key. +- `tfe_hostname`: Specifies the hostname of the Terraform Enterprise instance. +- `tfe_tls_cert_file`: Specifies the base64 encoded TLS certificate file. +- `tfe_tls_key_file`: Specifies the base64 encoded TLS key file. +- `tfe_tls_ca_bundle_file`: Specifies the base64 encoded TLS CA bundle file. + +Create file `var.hcl` and add the following variables: + +```hcl + path = "nomad/jobs/tfe-job/tfe-group/tfe-task" + namespace = "terraform-enterprise" + + items { + # The field should contain the base64 encoded value of the cert. Mappped to the TFE_TLS_CERT_FILE environment variable. + tfe_tls_cert_file = "" + + # The field should contain the base64 encoded value of the bundle. Mapped to the TFE_TLS_CA_BUNDLE_FILE environment variable. + tfe_tls_ca_bundle_file = "" + + # The field should contain the base64 encoded value of the key. Mappped to the TFE_TLS_KEY_FILE environment variable. + tfe_tls_key_file = "" + + # A valid TFE license. Mapped to the TFE_LICENSE environment variable. + tfe_license = "" + + # The hostname of the TFE instance. Mapped to the TFE_HOSTNAME environment variable. + tfe_hostname = "" + } + ``` + +`path` variable specifies the path where the Nomad variables will be stored. +Update the `path` variable if default value of `job_name` is overridden in the `var.hcl` file. + +Apply the Nomad variables to the job specification by running the following command: + ```bash + $ nomad var put @var.hcl + ``` + +Refer to [Nomad Variables](/nomad/docs/concepts/variables) in the Nomad documentation for additional information. + +Refer to the [example Nomad job specification](#nomad-job-specification) for additional guidance. + +## Configure Terraform Enterprise Nomad job specification + +This job is responsible for running the Terraform Enterprise image on Nomad. + +Refer to the [example Nomad job specification for TFE](/terraform/enterprise/flexible-deployments/install/nomad/install#nomad-job-specification-for-tfe) for a template that you can copy and modify. + +Pass the variables that you defined in the [Parameterize Terraform Enterprise settings](#parameterize-terraform-enterprise-settings) section. Refer to [Assigning Values to job Variables](/nomad/docs/job-specification/hcl2/variables#assigning-values-to-job-variables) in the Nomad documentation for instructions. The following variables are required: + +- `tfe_image_username` +- `tfe_image_password` + +The following variables are optional: + +- `tfe_image` +- `namespace` + +Terraform Enterprise does not use workload identities on Nomad v1.4 and older. If you are deploying to Nomad v1.4.x or older, complete the following steps: + +1. Manually create an ACL token. Refer to [Command: `acl token create`](/nomad/docs/commands/acl/token/create) in the Nomad documentation for instructions. +1. Remove the `identity` stanza. +1. Pass the ACL token to the Terraform Enterprise job. Export the token to the `NOMAD_TOKEN` environment variable and add it to the `env` stanza. + +Refer to the [example Nomad job specification](#nomad-job-specification) for a template that you can copy and modify. Run the `nomad job run` command and specify job configuration to submit the changes. Refer to [Command: job run](/nomad/docs/commands/job/run) in the Nomad documentation for additional information about the command. + +## Configure a Nomad batch job to run the Terraform Enterprise agent + +Terraform Enterprise creates ephemeral agent jobs to execute Terraform runs when operating in Remote execution mode. A run is an invocation of the `terraform plan` or `terraform apply` command. To enable this behavior, create a Nomad batch job specification that defines how Terraform Enterprise agents run on Nomad. + +You can use the [example Nomad batch job specification for TFE agent](/terraform/enterprise/flexible-deployments/install/nomad/install#nomad-batch-job-specification) as a template to copy and change. After registering the batch job in Nomad, manual execution of batch jobs is not required. When Terraform executes a plan or apply, it automatically dispatches the jobs as Nomad batch jobs and completes the run. + +Refer to [Batch Job](/nomad/docs/job-specification/job#batch-job) in the Nomad documentation for more information. + +## Run the Nomad jobs + +### 1. Deploy Terraform Enterprise Instance + +Run the `nomad job run` command to pull the Terraform Enterprise image and install the application. Pass the Terraform Enterprise job specification as the command argument. You must also provide the credentials for the registry to download the image: + +```shell-session +$ nomad job run \ + -var="tfe_image_username=$TFE_REGISTRY_USERNAME" \ + -var="tfe_image_password=$TFE_REGISTRY_PASSWORD" \ + +``` + +### 2. Register Terraform Agent Job +Run the `nomad job run` command and pass the Terraform agent job specification to register the batch job in Nomad: + +```shell-session +$ nomad job run +``` + +Alternatively, you can pull and install the Terraform Enterprise image using the Terraform Enterprise On Nomad Pack tool. Refer to the [`terraform-enterprise-fdo-nomad-pack` repository](https://github.com/hashicorp/nomad-pack-community-registry/tree/main/packs/tfe_fdo_nomad) on GitHub for instructions. + +## Post installation tasks + +Complete the following tasks after starting Terraform Enterprise. + +### Review startup checks + +When you start Terraform Enterprise, several startup checks also run to prevent errors related to invalid configurations or certificates, as well as other issues that could prevent the application from running successfully or safely. Refer to the [startup checks reference](/terraform/enterprise/deploy/reference/startup-checks) for additional information. + +### Create initial admin user + +[Provision your first administrative user](/terraform/enterprise/deploy/initial-admin-user) and start using Terraform Enterprise. + +## Deploy a load balancer to the Nomad Cluster (Optional) + +You can deploy a load balancer to the Nomad cluster so that you can manage external traffic loads. Refer to the [load balancer tutorial](/nomad/tutorials/load-balancing) in the Nomad documentation for instructions. +Refer to the [example NGINX configuration](/terraform/enterprise/flexible-deployments/install/nomad/install#nomad-nginx-job-for-load-balancing) for additional guidance. + +## Examples + +You can copy the following examples and modify the values to match your deployment. + +### Nomad job specification + +The following example configuration defines a Terraform Enterprise job specification. You can copy the example and modify the values to match your deployment. +This example uses minimal configuration options. Refer to [Configuration Reference](/terraform/enterprise/flexible-deployments/install/configuration) +for a list of all the configuration options. + +```hcl +variable "tfe_image" { + description = "The TFE image to use" + type = string + default = "images.releases.hashicorp.com/hashicorp/terraform-enterprise:v202408-1" +} + +variable "tfe_image_username" { + description = "Username for the registry to download TFE image" + type = string +} + +variable "tfe_image_password" { + description = "Password for the registry to download TFE image" + type = string +} + +variable "namespace" { + description = "The Nomad namespace to run the job" + type = string + default = "" +} + +job "tfe-job" { + datacenters = ["dc1"] + namespace = var.namespace + type = "service" + + group "tfe-group" { + count = 1 + + restart { + attempts = 3 + delay = "60s" + interval = "10m" + mode = "fail" + } + + update { + max_parallel = 1 + min_healthy_time = "30s" + healthy_deadline = "15m" + progress_deadline = "20m" + health_check = "checks" + } + + network { + port "tfe" { + # static port is not required if load balancer is used. + static = 443 + to = 8443 + } + port "tfehttp" { + # static port is not required if load balancer is used. + static = 80 + to = 8080 + } + port "vault" { + to = 8201 + } + } + + service { + name = "tfe-svc" + port = "tfe" + provider = "nomad" + check { + name = "tfe_probe" + type = "http" + protocol = "https" + port = "tfe" + path = "/_health_check" + interval = "5s" + timeout = "2s" + method = "GET" + } + } + + task "tfe-task" { + driver = "docker" + + identity { + # Expose Workload Identity in NOMAD_TOKEN env var + env = true + } + + template { + data = < | docker login --username terraform images.releases.hashicorp.com --password-stdin + ``` + +1. Pull the Terraform Enterprise image from the registry. + + ```shell-session + $ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + +1. Create a new project. + + ```shell-session + $ oc new-project + ``` + +1. Create an image pull secret in `` to fetch the `terraform-enterprise` container from the ``. This URL can be `images.releases.hashicorp.com`, or your internal container registry. If you are using `images.releases.hashicorp.com`, use `terraform` as the `` parameter in the following command with `--docker-password=$(cat /path/to/terraform.hclic)` + + ```shell-session + $ oc create secret docker-registry terraform-enterprise --docker-server= --docker-username= --docker-password= -n + ``` + +1. Add the Hashicorp Helm registry: + + ```shell-session + $ helm repo add hashicorp https://helm.releases.hashicorp.com + ``` + +1. Render the `terraform-enterprise` chart with your custom [values file](https://helm.sh/docs/chart_template_guide/values_files/) ``, for example `tmp/overrides.yaml`. + + ```shell-session + $ helm template terraform-enterprise hashicorp/terraform-enterprise –n --values + ``` + +1. Install `terraform-enterprise`, this step can take several minutes. + + ```shell-session + $ helm install terraform-enterprise hashicorp/terraform-enterprise –n --values + ``` + +1. Inspect `terraform-enterprise` pods to verify their successful start. + + ```shell-session + $ oc get pods -n + ``` + + If Terraform Enterprise pods fail to start, refer to [Kubernetes Troubleshooting](/terraform/enterprise/deploy/troubleshoot#kubernetes). + +1. By default, Terraform Enterprise installs a load balancer service. Retrieve the external IP address of this service. + + ```shell-session + $ oc get services -n + ``` + +1. Set up a DNS record that points to your external IP address to enable routing to your ``. A DNS address is required to communicate with Terraform Enterprise, and it is managed outside of OpenShift and the Terraform Enterprise helm chart or application. + +1. Validate the readiness of the Terraform Enterprise application by querying the health check endpoint. + + ```shell-session + $ curl https://tfe.test.hashicorp.com/_health_check + ``` + +## Post installation tasks + +Complete the following tasks after the initial installation. + +### Review startup checks + +When you start Terraform Enterprise, several startup checks also run to prevent errors related to invalid configurations or certificates, as well as other issues that could prevent the application from running successfully or safely. Refer to the [startup checks reference](/terraform/enterprise/deploy/reference/startup-checks) for additional information. + +### Configuring a route + +When you deploy Terraform Enterprise to OpenShift, the Helm chart does not create an [OpenShift route](https://docs.openshift.com/container-platform/latest/networking/routes/route-configuration.html) by default. + +Provisioning a route creates a public-facing URL at which users can access the Terraform Enterprise UI and API. + +```shell-session +$ oc expose svc/terraform-enterprise --hostname terraform-enterprise.apps. --name terraform-enterprise -n +``` +-> **Note:** Use the options on the `oc expose` command to tailor the route to the needs of your environment. + +The newly created route can then be retrieved from the cluster: + +```shell-session +$ oc get routes +NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD +terraform-enterprise terraform-enterprise.apps. terraform-enterprise https-port reencrypt/Redirect None +``` + +### Create the initial admin user + +[Provision your first administrative user](/terraform/enterprise/deploy/initial-admin-user) and start using Terraform Enterprise. + +### Extend or fork the OpenShift `terraform-enterprise` helm chart + +The [Terraform Enterprise Helm Chart](https://github.com/hashicorp/terraform-enterprise-helm) is intended to meet the needs of the majority of our users. Many OpenShift primitives, such as routing, are absent in the `terraform-enterprise` Helm chart. You can fork our Helm chart and adapt it to your organization’s requirements. Alternatively, you can use the `terraform-enterprise` Helm chart as a [sub-chart](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/), thus relegating OpenShift primitives to the parent chart to be deployed around the `terraform-enterprise` chart contents. + +If you contact HashiCorp support, include your custom Helm chart alongside your support bundle to ensure support has all the information they need. + +## Example deployment configuration + +The following example configuration deploys Terraform Enterprise to OpenShift in Azure with hosted external services. The configuration is based on cloud native hosted PostgreSQL, storage, or Redis cache services. You can copy the example configuration and modify the values to per your environment. Refer to [Configuration Reference](/terraform/enterprise/deploy/reference/configuration) +for a list of all configuration options. + +The example also depends on the following conditions: + +- Values under `.env.variables` are set as a `ConfigMap` and mounted as Terraform Enterprise environment variables. +- Values under `.env.secrets` are set as Kubernetes secrets and mounted as Terraform Enterprise environment variables. +- Extend the `env.configMapRefs[]` or `env.secretRefs[]` with your own resources to add additional `ConfigMap` or `Secret` resources within your environment configuration. + +- Values marked `BASE_64_ENCODED*` indicate that the value given must be base 64 encoded. If you are using this certificate configuration to host Terraform Enterprise web traffic, this value must be valid with the `env.TFE_HOSTNAME`, or match the wildcard pattern. + +```yaml +replicaCount: +tls: + certData: + keyData: + caCertData: +image: + repository: images.releases.hashicorp.com + name: hashicorp/terraform-enterprise + tag: +openshift: + enabled: true +env: + variables: + TFE_HOSTNAME: + TFE_IACT_SUBNETS: + + # Database settings. + TFE_DATABASE_HOST: + TFE_DATABASE_NAME: + TFE_DATABASE_PARAMETERS: + TFE_DATABASE_USER: + + # Redis settings. + TFE_REDIS_HOST: + TFE_REDIS_USE_TLS: + TFE_REDIS_USE_AUTH: + TFE_REDIS_USER: + + # Azure container storage settings. + TFE_OBJECT_STORAGE_TYPE: azure + TFE_OBJECT_STORAGE_AZURE_ACCOUNT_NAME: + TFE_OBJECT_STORAGE_AZURE_CONTAINER: + TFE_OBJECT_STORAGE_AZURE_ENDPOINT: + + # Terraform Enterprise on OpenShift Required settings + TFE_RUN_PIPELINE_IMAGE: + TFE_RUN_PIPELINE_KUBERNETES_IMAGE_PULL_SECRET_NAME: + + secrets: + TFE_DATABASE_PASSWORD: '' + TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY: '' + TFE_REDIS_PASSWORD: '' + TFE_LICENSE: '' + TFE_ENCRYPTION_PASSWORD: '' +``` + + +Refer to the following materials for additional guidance on setting up Helm chart values files: +- [Terraform Enterprise Helm repository](https://github.com/hashicorp/terraform-enterprise-helm) +- [Release version tags](/terraform/enterprise/releases) +- Generic reference for [values file](https://helm.sh/docs/chart_template_guide/values_files/) to override the default values in the Helm chart. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/podman.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/podman.mdx new file mode 100644 index 0000000000..eb29ccb0ae --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/podman.mdx @@ -0,0 +1,493 @@ +--- +page_title: Deploy Terraform Enterprise to Podman +description: >- + Learn how to deploy Terraform Enterprise using Podman. +--- + +# Deploy Terraform Enterprise to Podman + +This topic describes how to install and run Terraform Enterprise on Podman. These installation steps set up a rootful Podman installation with a non-root user so that the Podman service runs as root while processes within the Terraform Enterprise container run as non-root. + +## Overview + +Complete the following steps to install Terraform Enterprise: + +1. Complete the prerequisites. +1. Set up installation folders and files. +1. Download and install image. +1. Apply the deployment configuration. + +## Prerequisites + +Complete the following tasks before attempting to install Terraform Enterprise. + +### Prepare the deployment environment + +Set up a host instance and provide a DNS hostname for Terraform Enterprise and the associated TLS certificate. Additionally, you must configure your network so that your host can receive and send traffic. Refer to [Prepare the host environment](/terraform/enterprise/deploy/prepare-host) for details about preparing the host environment. + +### Deploy storage systems for `active` and `external` mode + +If you intend to operate Terraform Enterprise in `active` or `external` mode, deploy the database and other storage devices so that Terraform can connect to them when the application starts. Refer to [Data storage settings overview](/terraform/enterprise/deploy/configuration/storage) for additional information. + +### Create the deployment configuration + +Create a deployment configuration file and specify settings for the operational mode, license, TLS certificates, and network configuration. Add any additional configurations necessary for your environment. Refer to [Configuration file overview](/terraform/enterprise/deploy/configuration/) for additional information. + +## Set up installation folders and files + +1. Connect to the host instance. +1. Create a dedicated directory for the Terraform Enterprise installation files +1. Navigate to the installation directory. +1. Create a `certs` directory. +1. Place your TLS certificate (`cert.pem`), TLS private key (`key.pem`), and CA certificates bundle (`bundle.pem`) inside inside the`certs` directory. If you do not have a CA certificates bundle, place your TLS certificate (`cert.pem`) inside `bundle.pem` instead. +1. Place your deployment configuration file into the Terraform Enterprise installation directory. Refer to [Example deployment configurations](#example-deployment-configurations) for pre-formatted configurations that you can copy and modify. Refer to the [configuration reference](/terraform/enterprise/deploy/reference/configuration) for information about all deployment configuration settings. + +## Download and install image + + 1. Log in to the Terraform Enterprise container image registry, using `terraform` + as the username, and your Hashicorp Terraform Enterprise license as the password: + + ```shell-session + # echo "" | podman login --username terraform images.releases.hashicorp.com --password-stdin + ``` + + 1. Pull the Terraform Enterprise image from the registry. + + ```shell-session + # podman pull images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + +## Apply the deployment configuration + +Refer to [Deployment configuration reference](/terraform/enterprise/deploy/reference/configuration) for a list of all the configuration options. + + 1. Create a Terraform Enterprise pod by running the following command: + + ```shell-session + # podman kube play + ``` + + 1. In a separate terminal session, you can monitor the logs by running the following command: + + ```shell-session + # podman logs -f + ``` + + 1. Monitor the health of the application until it starts reporting healthy with the following command: + + ```shell-session + # podman exec tfe-health-check-status + ``` + +## Post installation tasks actions + +Complete the following tasks after the initial installation. + +### Review startup checks + +When you start Terraform Enterprise, several startup checks also run to prevent errors related to invalid configurations or certificates, as well as other issues that could prevent the application from running successfully or safely. Refer to the [startup checks reference](/terraform/enterprise/deploy/reference/startup-checks) for additional information. + +### Create the initial admin user + +[Provision your first administrative user](/terraform/enterprise/deploy/initial-admin-user) and start using Terraform Enterprise. + +### Service management + +To learn more about managing the lifecycle of Podman pods, refer to [the Podman docs for more information about pods](https://podman.io/). +We have included possible options for managing a pod's lifecycle on a Red Hat Enterprise Linux (RHEL) host for convenience. + +### Manage Podman service + +Complete the following steps to create a `systemd` service that automatically starts your pod and its containers. We +recommend using [Quadlet](https://www.redhat.com/sysadmin/quadlet-podman), which is an opinionated tool for running Podman +containers, to deploy `systemd`. Quadlet generates a `systemd` service that manages the Terraform Enterprise pod and +all containers, including the internal infrastructure container. + + 1. Ensure the Terraform Enterprise pod is not running. + + 1. Navigate to `/etc/containers/systemd/`. Define the service files in this directory. + + 1. Create a Quadlet unit file for the Terraform Enterprise pod and container at `/etc/containers/systemd/terraform-enterprise.kube`: + ```ini + [Install] + WantedBy=default.target + [Service] + Restart=always + [Kube] + Yaml=tfe.yaml + ``` + + 1. Copy your Kubernetes YAML file to `/etc/containers/systemd/tfe.yaml`: + ```shell-session + # cp /etc/containers/systemd/tfe.yaml + ``` + + 1. Reload the `systemd` daemon and enable the service: + ```shell-session + # systemctl daemon-reload + # systemctl start terraform-enterprise.service + ``` + + 1. Check the status of your service: + ```shell-session + # systemctl status terraform-enterprise.service + + ● terraform-enterprise.service + Loaded: loaded (/etc/containers/systemd/terraform-enterprise.kube; generated) + Active: active (running) since Sun 2024-02-25 21:15:55 UTC; 15min ago + Main PID: 35893 (conmon) + Tasks: 4 (limit: 404901) + Memory: 5.2M + CGroup: /system.slice/terraform-enterprise.service + ├─35893 /usr/bin/conmon --api-version 1 -c 74f1271d9a481711950c62b509f126c3fdf8678a9d552c5ccc692eb6ed5cf4d1 -u 74f1271d9a481711950c62b509f126c3fdf8678a9d552c5ccc692eb6ed5cf4d1 -> + ├─36028 /usr/sbin/dnsmasq -u root --conf-file=/run/containers/cni/dnsname/podman-default-kube-network/dnsmasq.conf + ├─36030 /usr/bin/conmon --api-version 1 -c 973d3ff4f7ada5880a9947be4d90b3d556c7ce841037de34c7eaa07c044a3ec0 -u 973d3ff4f7ada5880a9947be4d90b3d556c7ce841037de34c7eaa07c044a3ec0 -> + └─36083 /usr/bin/conmon --api-version 1 -c 435ea68e87dbef3c0965ffdfb9fe1fc36c5500a63eb00dc0fe2499aaa560a563 -u 435ea68e87dbef3c0965ffdfb9fe1fc36c5500a63eb00dc0fe2499aaa560a563 -> + ``` + +## Example configurations + +You can copy one of the following example configurations and modify the values to per your environment. Refer to [Configuration Reference](/terraform/enterprise/deploy/reference/configuration) +for a list of all configuration options. + + +### Example `disk` mode configuration + +The following Kubernetes YAML deploys Terraform Enterprise in `disk` mode. In this mode, Terraform Enterprise runs as a pod composed of a Terraform Enterprise container. + +```yaml +--- +apiVersion: "v1" +kind: "Pod" +metadata: + labels: + app: "terraform-enterprise" + name: "terraform-enterprise" +spec: + restartPolicy: "Never" + containers: + - env: + - name: "TFE_OPERATIONAL_MODE" + value: "disk" + - name: "TFE_LICENSE" + value: "" + - name: "TFE_HOSTNAME" + value: "" + - name: "TFE_HTTP_PORT" + value: "8080" + - name: "TFE_HTTPS_PORT" + value: "8443" + - name: "TFE_TLS_CERT_FILE" + value: "/etc/ssl/private/terraform-enterprise/cert.pem" + - name: "TFE_TLS_KEY_FILE" + value: "/etc/ssl/private/terraform-enterprise/key.pem" + - name: "TFE_TLS_CA_BUNDLE_FILE" + value: "/etc/ssl/private/terraform-enterprise/bundle.pem" + - name: "TFE_DISK_CACHE_VOLUME_NAME" + value: "terraform-enterprise_terraform-enterprise-cache" + - name: "TFE_ENCRYPTION_PASSWORD" + value: '' + image: "images.releases.hashicorp.com/hashicorp/terraform-enterprise:" + name: "terraform-enterprise" + ports: + - containerPort: 8080 + hostPort: 80 + - containerPort: 8443 + hostPort: 443 + - containerPort: 9090 + hostPort: 9090 + securityContext: + capabilities: + add: + - "CAP_IPC_LOCK" + readOnlyRootFilesystem: true + seLinuxOptions: + type: "spc_t" + volumeMounts: + - mountPath: "/etc/ssl/private/terraform-enterprise" + name: "certs" + - mountPath: "/var/log/terraform-enterprise" + name: "log" + - mountPath: "/run" + name: "run" + - mountPath: "/tmp" + name: "tmp" + - mountPath: "/var/lib/terraform-enterprise" + name: "data" + - mountPath: "/run/docker.sock" + name: "docker-sock" + - mountPath: "/var/cache/tfe-task-worker/terraform" + name: "terraform-enterprise_terraform-enterprise-cache-pvc" + volumes: + - hostPath: + path: "" + type: "Directory" + name: "certs" + - emptyDir: + medium: "Memory" + name: "log" + - emptyDir: + medium: "Memory" + name: "run" + - emptyDir: + medium: "Memory" + name: "tmp" + - hostPath: + path: "" + type: "Directory" + name: "data" + - hostPath: + path: "/run/podman/podman.sock" + type: "File" + name: "docker-sock" + - name: "terraform-enterprise_terraform-enterprise-cache-pvc" + persistentVolumeClaim: + claimName: "terraform-enterprise_terraform-enterprise-cache" +``` + +### Example `external` mode configuration + +The following Kubernetes YAML configuration deploys Terraform Enterprise in `external` mode. In this mode, Terraform Enterprise runs as a pod composed of a Terraform Enterprise container. + +```yaml +--- +apiVersion: "v1" +kind: "Pod" +metadata: + labels: + app: "terraform-enterprise" + name: "terraform-enterprise" +spec: + restartPolicy: "Never" + containers: + - env: + - name: "TFE_LICENSE" + value: "" + - name: "TFE_HOSTNAME" + value: "" + - name: "TFE_OPERATIONAL_MODE" + value: "external" + - name: "TFE_HTTP_PORT" + value: "8080" + - name: "TFE_HTTPS_PORT" + value: "8443" + - name: "TFE_ENCRYPTION_PASSWORD" + value: '' + - name: "TFE_DISK_CACHE_VOLUME_NAME" + value: "terraform-enterprise_terraform-enterprise-cache" + - name: "TFE_TLS_CA_BUNDLE_FILE" + value: "/etc/ssl/private/terraform-enterprise/bundle.pem" + - name: "TFE_TLS_CERT_FILE" + value: "/etc/ssl/private/terraform-enterprise/cert.pem" + - name: "TFE_TLS_KEY_FILE" + value: "/etc/ssl/private/terraform-enterprise/key.pem" + + + # Database settings. See the configuration reference for more settings. + - name: "TFE_DATABASE_HOST" + value: "" + - name: "TFE_DATABASE_NAME" + value: "" + - name: "TFE_DATABASE_PARAMETERS" + value: "" + - name: 'TFE_DATABASE_PASSWORD' + value: "" + - name: "TFE_DATABASE_USER" + value: "" + + # Object storage settings. See the configuration reference for more settings. + - name: "TFE_OBJECT_STORAGE_TYPE" + value: "s3" + - name: "TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID" + value: "" + - name: "TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY" + value: '' + - name: "TFE_OBJECT_STORAGE_S3_BUCKET" + value: "" + - name: "TFE_OBJECT_STORAGE_S3_REGION" + value: "" + + image: "images.releases.hashicorp.com/hashicorp/terraform-enterprise:" + name: "terraform-enterprise" + ports: + - containerPort: 8080 + hostPort: 80 + - containerPort: 8443 + hostPort: 443 + - containerPort: 9090 + hostPort: 9090 + securityContext: + capabilities: + add: + - "CAP_IPC_LOCK" + readOnlyRootFilesystem: true + seLinuxOptions: + type: "spc_t" + volumeMounts: + - mountPath: "/etc/ssl/private/terraform-enterprise" + name: "certs" + - mountPath: "/var/log/terraform-enterprise" + name: "log" + - mountPath: "/run" + name: "run" + - mountPath: "/tmp" + name: "tmp" + - mountPath: "/run/docker.sock" + name: "docker-sock" + - mountPath: "/var/cache/tfe-task-worker/terraform" + name: "terraform-enterprise_terraform-enterprise-cache-pvc" + volumes: + - hostPath: + path: "" + type: "Directory" + name: "certs" + - emptyDir: + medium: "Memory" + name: "log" + - emptyDir: + medium: "Memory" + name: "run" + - emptyDir: + medium: "Memory" + name: "tmp" + - hostPath: + path: "/run/podman/podman.sock" + type: "File" + name: "docker-sock" + - name: "terraform-enterprise_terraform-enterprise-cache-pvc" + persistentVolumeClaim: + claimName: "terraform-enterprise_terraform-enterprise-cache" +``` + +### Example `active-active` mode configuration + +The following Kubernetes YAML configuration deploys Terraform Enterprise in `active-active` mode. In this mode, +each node runs a Podman pod composed of a Terraform Enterprise container. + +```yaml +--- +apiVersion: "v1" +kind: "Pod" +metadata: + labels: + app: "terraform-enterprise" + name: "terraform-enterprise" +spec: + containers: + - env: + - name: "TFE_LICENSE" + value: "" + - name: "TFE_HOSTNAME" + value: "" + - name: "TFE_HTTP_PORT" + value: "8080" + - name: "TFE_HTTPS_PORT" + value: "8443" + - name: "TFE_OPERATIONAL_MODE" + value: "active-active" + - name: "TFE_ENCRYPTION_PASSWORD" + value: '' + - name: "TFE_DISK_CACHE_VOLUME_NAME" + value: "terraform-enterprise_terraform-enterprise-cache" + - name: "TFE_TLS_CA_BUNDLE_FILE" + value: "/etc/ssl/private/terraform-enterprise/bundle.pem" + - name: "TFE_TLS_CERT_FILE" + value: "/etc/ssl/private/terraform-enterprise/cert.pem" + - name: "TFE_TLS_KEY_FILE" + value: "/etc/ssl/private/terraform-enterprise/key.pem" + + # Database settings. See the configuration reference for more settings. + - name: "TFE_DATABASE_HOST" + value: "" + - name: "TFE_DATABASE_NAME" + value: "" + - name: "TFE_DATABASE_PARAMETERS" + value: "" + - name: "TFE_DATABASE_PASSWORD" + value: '' + - name: "TFE_DATABASE_USER" + value: "" + + # Object storage settings. See the configuration reference for more settings. + - name: "TFE_OBJECT_STORAGE_TYPE" + value: "s3" + - name: "TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID" + value: "" + - name: "TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY" + value: '' + - name: "TFE_OBJECT_STORAGE_S3_BUCKET" + value: "" + - name: "TFE_OBJECT_STORAGE_S3_REGION" + value: "" + + # Redis settings. See the configuration reference for more settings. + - name: "TFE_REDIS_HOST" + value: "" + - name: "TFE_REDIS_PASSWORD" + value: '' + - name: "TFE_REDIS_USER" + value: "" + - name: "TFE_REDIS_USE_AUTH" + value: "" + - name: "TFE_REDIS_USE_TLS" + value: "" + + # Vault cluster settings. + # If you are using the default internal vault, this should be the private routable IP address of the node itself. + - name: "TFE_VAULT_CLUSTER_ADDRESS" + value: "https://10.0.66.189:8201" + + image: "images.releases.hashicorp.com/hashicorp/terraform-enterprise:" + name: "terraform-enterprise" + ports: + - containerPort: 8080 + hostPort: 80 + - containerPort: 8443 + hostPort: 443 + - containerPort: 8201 + hostPort: 8201 + - containerPort: 9090 + hostPort: 9090 + securityContext: + capabilities: + add: + - "CAP_IPC_LOCK" + readOnlyRootFilesystem: true + seLinuxOptions: + type: "spc_t" + volumeMounts: + - mountPath: "/etc/ssl/private/terraform-enterprise" + name: "certs" + - mountPath: "/var/log/terraform-enterprise" + name: "log" + - mountPath: "/run" + name: "run" + - mountPath: "/tmp" + name: "tmp" + - mountPath: "/run/docker.sock" + name: "docker-sock" + - mountPath: "/var/cache/tfe-task-worker/terraform" + name: "terraform-enterprise_terraform-enterprise-cache-pvc" + restartPolicy: "Never" + volumes: + - hostPath: + path: "" + type: "Directory" + name: "certs" + - emptyDir: + medium: "Memory" + name: "log" + - emptyDir: + medium: "Memory" + name: "run" + - emptyDir: + medium: "Memory" + name: "tmp" + - hostPath: + path: "/run/podman/podman.sock" + type: "File" + name: "docker-sock" + - name: "terraform-enterprise_terraform-enterprise-cache-pvc" + persistentVolumeClaim: + claimName: "terraform-enterprise_terraform-enterprise-cache" +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/prepare-host.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/prepare-host.mdx new file mode 100644 index 0000000000..67b79b3692 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/prepare-host.mdx @@ -0,0 +1,156 @@ +--- +page_title: Prepare host environment +description: This topic describes how to configure the host environment for running Terraform Enterprise. +--- + +# Prepare the Terraform Enterprise host environment + +This topic describes how to prepare a Linux instance on your cloud provider to host a non-Replicated Terraform Enterprise deployment. For information about deploying to Replicated, refer to [Deploy to Replicated](/terraform/enterprise/deploy/replicated). + +## Overview + +Complete the following steps to set up your Terraform Enterprise host environment: + +1. Determine which runtime is most suitable for your architecture. +1. Provide a DNS hostname for Terraform Enterprise and the associated TLS certificate. +1. Configure your network so that your host can receive and send traffic. + +## Requirements + +The requirements depend on the runtime platform you intend to use. + +### Docker + +Terraform Enterprise supports the following versions of Docker Engine that can run amd64 containers. We do not publish arm64 images: + +- 23.0.x +- 24.0.x +- 25.0.x +- 26.0.x +- 26.1.x + +### Kubernetes + +You can create a host for your Terraform Enterprise Kubernetes cluster on the following cloud service providers: + +- Amazon Elastic Kubernetes Service (EKS) +- Google Cloud Google Kubernetes Engine (GKE) + - GKE Autopilot. Refer to [Increase run capacity](/terraform/enterprise/deploy/kubernetes/scale/run-capacity) for additional information. +- Azure Kubernetes Service (AKS) + + +You can install Terraform Enterprise using the Helm CLI version 3.0 or later. Refer to the [Helm documentation](https://helm.sh/docs/intro/install/) for instructions on installing Helm. + +### Nomad + +- Nomad v1.5.0 and newer. + +### OpenShift + +You can create a host for your Terraform Enterprise OpenShift cluster on the following cloud service providers: + +- AWS Elastic Kubernetes Service (EKS) +- Google Cloud Google Kubernetes Engine (GKE) +- Azure Azure Kubernetes Service (AKS) + +You can install Terraform Enterprise using the Helm CLI version 3.0 or later. Refer to the [Helm documentation](https://helm.sh/docs/intro/install/) for instructions on installing Helm. + +### Podman + +- Podman v4.3.0 or later. +- If installing on Red Hat Enterprise Linux (RHEL), RHEL 8 or later is required. + +## Install the runtime + +Refer to the documentation for your runtime for installation instructions: + +- [Install Docker Engine](https://docs.docker.com/engine/install/) for your operating system. +- [Install Kubernetes](https://kubernetes.io/docs/tasks/tools/) +- [Install OpenShift](https://docs.openshift.com/container-platform/latest/installing/overview/index.html) +- [Install Podman](https://podman.io/docs/installation) +- [Install Nomad](/nomad/docs/install) + +### Enable the Podman socket + +If you are deploying to Podman, set up Podman’s docker-compatible REST API that runs as a `systemd` socket-activated service: + +```shell-session +$ systemctl enable --now podman.socket +``` + +### Set the security context for Podman on RHEL and SELinux + +We recommend adding `type: spc_t` to the `kube.yaml` file when using volumes for an unprivileged Podman container on an SELinux-enabled system. This setting ensures the correct permissions are in place to access the volume when Terraform Enterprise creates the pod and container. + +Specify the value in the Kubernetes pod specification's security context: + +```yaml +"securityContext": + "seLinuxOptions": + "type": "spc_t" +``` + +## Assign a DNS hostname + +Terraform Enterprise requires a DNS hostname so that it is accessible to users and services. Refer to the documentation for your cloud provider for instructions. + +You can add a secondary hostname so that users can access Terraform Enterprise using an alternative address. For example, you can provide an address for OIDC workload identity federation or to let external users to interact with Terraform Enterprise. + +Refer to [Configure network settings](/terraform/enterprise/deploy/configuration/network) for instructions. + +## Create TLS certificates + +Generate the following TLS certificates: + +- `cert.pem`: The end-entity certificate for your DNS hostname with any intermediate certificates appended to it. +- `key.pem`: The private key for the end-entity certificate. Must not be protected by a passphrase. +- `bundle.pem`: Additional certificates to be added to the Certificate Authority (CA) bundle. + +If your certificate files are from Let’s Encrypt, the file names map to the following Terraform Enterprise files: + +| Terraform Enterprise | Let's Encrypt | +| --- | --- | +| key.pem | privkey.pem | +| cert.pem | fullchain.pem | +| bundle.pem | fullchain.pem | + +If you do not have a certificate, you can generate a self-signed certificate. + +The following example uses the `openssl` command to generate an RSA key and certificate for `MyOrganization`. Specify details about your organization in the `-subj` flag or omit and enter them when prompted. Refer to the [OpenSSL documentation](https://docs.openssl.org/master/man1/openssl-req/) for information about forming the command. The `-nodes` option is required because Terraform Enterprise cannot use a private key that is protected by a passphrase. + +```shell-session +openssl req -nodes -x509 -sha256 -newkey rsa:4096 \ + -keyout cert.key \ + -out cert.crt \ + -days 356 \ + -subj "/C=US/ST=CA/L=San Francisco/O=MyOrganization/OU=Global/CN=example.com" \ + -addext "subjectAltName=DNS:example.com" +``` + +When generating the key, replace `` with the Terraform Enterprise hostname: + +```shell-session +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:US +State or Province Name (full name) [Some-State]:California +Locality Name (eg, city) []:San Francisco +Organization Name (eg, company) [Internet Widgits Pty Ltd]:HashiCorp, Inc. +Organizational Unit Name (eg, section) []:Engineering +Common Name (e.g. server FQDN or YOUR name) []: +Email Address []: +``` + +Copy the `cert.pem` file to a new file named `bundle.pem`: + +```shell-session +$ cp cert.pem bundle.pem +``` + +## Configure network access +You must configure the host to allow traffic to and from the Linux instance that Terraform Enterprise runs in. Refer to [Configure network access](/terraform/enterprise/deploy/configuration/network) for instructions. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/application-security.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/application-security.mdx new file mode 100644 index 0000000000..eb0a2f4fa8 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/application-security.mdx @@ -0,0 +1,11 @@ +--- +page_title: Terraform Enterprise security reference +description: >- + Learn about Terraform Enterprise application roles and security best practices. +--- + +# Terraform Enterprise security reference + +This page explains the aspects of the Terraform security model that are unique to Terraform Enterprise. We recommend also reviewing the core concepts in [HCP Terraform Security model](/terraform/cloud-docs/architectural-details/security-model). + +@include "replicated-and-fdo/architecture/security-model-partial.mdx" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/cli.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/cli.mdx new file mode 100644 index 0000000000..1a39c49278 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/cli.mdx @@ -0,0 +1,340 @@ +--- +page_title: Terraform Enterprise admin CLI reference +description: >- + Learn how to use `tfectl` subcommands to manage your Terraform Enterprise deployment. +--- + +# Terraform Enterprise admin CLI reference + +This topic provides reference information about `tfectl` commands that enable you to manage and administrate your Terraform Enterprise deployment. + +## Introduction + +Terraform Enterprise includes a command line interface that enable you to change its configuration, stop the application safely, and produce support bundles. You must have access into the Docker container or Kubernetes pod to run these commands. For instructions on connecting to the command line, refer to [Access the Terraform Enterprise command line](/terraform/enterprise/deploy/manage/access-cli). + +## `tfectl` command + +The `tfectl` command is the root of the interface. It exposes a number of commands to perform different operations. + +Most of the commands run directly on the node where Terraform Enterprise executes them. Some commands support a `--node` flag that you can use to specify which node to run a command on. The value of `--node` depends on the runtime environment of the Terraform Enterprise installation i.e: +- Container ID (Docker) +- Pod Name (Kubernetes) +- Hostname + + +Multi node commands are only relevant and possible if you are running Terraform Enterprise on Kubernetes, or on another deployment option using the 'active-active' operational mode. + + +## Gracefully stop work on a node + +This command stops a terraform-enterprise node from executing new plans and applies. It allows the current work to complete before safely stopping the node from picking up any new tasks, which lets you safely stop the application. + +Drain a single node. + +```shell-session +$ tfectl node drain --node NODE_NAME +``` + +If you do not provide the `--node` flag, the command will drain the node you run it on. + +```shell-session +$ tfectl node drain +``` + +Use the `--all` flag to drain all the nodes. + +```shell-session +$ tfectl node drain --all +``` + +Restart the application to resume processing work after draining all the nodes. + +## Support bundle + +The `support bundle` command generates support bundle on a Terraform Enterprise installation. + +Generate a support bundle on a specific node. + +```shell-session +$ tfectl support bundle --node NODE_NAME +``` + +If you do not provide the `--node` flag, Terraform Enterprise will by default generate the support bundle on the same node where you run the command. + +```shell-session +$ tfectl support bundle +``` + +Use the `--all` flag to generate the support bundle on all the nodes. + +```shell-session +$ tfectl support bundle --all +``` + +For mounted disk installations, Terraform Enterprise will generate support bundles in `/run/terraform-enterprise/support-bundles`. Downloading this file makes it immediately available, but it should be disabled once the file has been downloaded. + +For External Services, Active/Active and Kubernetes installations, Terraform Enterprise will upload the support bundles to the same object store bucket where Terraform state files are stored. +Each specific run of the admin `support bundle` command will upload the bundle to a directory with the same JobID, which is a timestamp in +[RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) format (`bucket/node/timestamp`). + +If you are sending a support bundle to HashiCorp Support, package and send all associated bundles to ensure that we have all the necessary information. + +Example upload structure: + +```shell-session +support-bundles +└── 2020-11-10T02:03:05Z + ├── 10.0.0.5 + │ └── 10.0.0.5-support-bundle-timestamp.tar.gz + └── 10.0.0.6 + └── 10.0.0.6-support-bundle-timestamp.tar.gz +``` + +## Enable or disable support bundle downloads + +The `support bundle-download` command enables the administrator of a mounted disk installation to access support bundles via https in the Terraform Enterprise node. + +To enable downloads, use the `--enable` flag. + +```shell-session +$ tfectl support bundle-download --enable +``` + +By enabling this feature, you will be able to download support bundles from `https://${TFE_HOSTNAME}/_support-bundles/${timestamp}/${filename}`. The filename follows the structure of `${node_hostname}-support-bundle-${timestamp}.tar.gz`. + +Once you have finished downloading support bundles, it is recommended to disable this feature using the following command: + +```shell-session +$ tfectl support bundle-download --disable +``` + +If the command is executed in a Terraform Enterprise installation that is not running on a mounted disk, it will have no effect and perform no action. + +## Connect to the internal Rails Console + +At times, it may become necessary to modify the internal state of the Terraform Enterprise application. An example is when you have lost credentials +for all your admin accounts and need to manually set an existing user as an administrator. + +This operation is very **dangerous**, and we strongly advise against using this command without the guidance of HashiCorp support. +Once you have a concrete action plan on what needs to be changed via the Rails console, execute: + +```shell-session +$ tfectl support console +``` + +This will prompt you for confirmation. Only the word `yes` is a valid response to proceed. + +## Review HashiCorp license status + +This command displays the status of the license installed on your Terraform Enterprise application. + +```shell-session +$ tfectl app license +``` + +## Retrieve the initial admin user creation token + +To create the first admin user in your Terraform Enterprise installation, you will need the **Initial Admin Creation Token** or **IACT**. +You can retrieve this from any Terraform Enterprise node using: + +```shell-session +$ tfectl admin token +``` + +This command should return the token value. You can also retrieve the REST resource that will allow you to create your +initial admin user with the IACT token appended at the end via the flag: + +```shell-session +$ tfectl admin token --url +``` + +This will provide the URL formatted to be used with `curl` or `wget`, and it only supports `POST` operations. + +## Generate product usage report + +The `admin usage-report` command generates a product usage report in JSON format that you can view and download. + +```shell-session +$ tfectl admin usage-report +``` + +When in `external` and `active-active` mode and on Kubernetes, Terraform Enterprise uploads the product usage report to the same object store bucket where Terraform state files are stored. + +Each specific run of the admin `usage-report` command generates the product usage report in a new JSON file. + +To send product usage reports to HashiCorp, visit the [**Licensing utilization reporting** page](https://portal.cloud.hashicorp.com/license-utilization/reports/create) and use the upload form. + +## List all Terraform Enterprise installation nodes + +To get a list of valid node values, use the following command: + +```shell-session +$ tfectl node list +``` + +This will return a list of all active nodes in the installation that are sharing the same database connection. + +## View application health + +Terraform Enterprise runs several integral systems for the application's overall health. +To view the health of these systems, run the following command: + +```shell-session +$ tfectl app status +``` + +You can also view the health on other nodes in the Terraform Enterprise installation. To see the status of a specific node, use the `--node` flag, e.g.: + + +```shell-session +$ tfectl app status --node NODE_NAME +``` + +For a health check on every node in the Terraform Enterprise installation, you could run: + +```shell-session +$ tfectl app status --all +``` + +## View application configuration + +Reviewing the actual values used by the Terraform Enterprise application during execution is a useful method to verify +correct configuration. To view it, simply run: + +```shell-session +$ tfectl app config +``` + +This command will print the application's configuration in JSON format, with sensitive values redacted. To see +the configuration without redaction, use: + +```shell-session +$ tfectl app config --unredacted +``` + +However, some values, like the `TLS CA Bundle Data`, are truncated for readability. For the full configuration +without truncation, use: + +```shell-session +$ tfectl app config --full +``` + +You can save the configuration to a file with: + +```shell-session +$ tfectl app config --out /path/to/config.json +``` + +To get the node's configuration from a specific node: + +```shell-session +$ tfectl app config --node NODE_NAME +``` + +To read the configuration from all the nodes in the Terraform Enterprise installation, you can use: + +```shell-session +$ tfectl app config --all +``` + +To convert your Terraform Enterprise configuration into a suitable Docker Compose file format, use the following command: + +```shell-session +$ tfectl app config --format docker +``` +Use this command when migrating from a Replicated installation to another deployment option. + +## Change encryption password + +The `TFE_ENCRYPTION_PASSWORD` is used as a key for envelope encryption. This password is necessary to start and run Terraform Enterprise. The blob data cannot be decrypted without it. To change it, use: + +```shell-session +$ tfectl app rotate-encryption-password +``` + +You'll be prompted for confirmation, where 'yes' is the only acceptable value. Then, you'll need to provide your current +and new passwords: + +```shell-session +$ tfectl app rotate-encryption-password --current CURRENT_PASSWORD --new NEW_PASSWORD +``` + +**WARNING**: After changing the encryption password, restart your Terraform Enterprise nodes with the new password as the value of the `TFE_ENCRYPTION_PASSWORD` environment variable. +Ensure no one is using the system to avoid corrupting the application's state. + +Back up the old password in case you need to restore the application. Otherwise, data in the backup can't be accessed. + +## Trigger startup checks + +Terraform Enterprise runs validations to ensure proper application configuration. Use the following commands to manually trigger the validations: + +```shell-session +$ tfectl app startup-check +``` + +## View ongoing database migrations + +This command retrieves the current version of the ongoing database migrations: + +```shell-session +$ tfectl db last-applied-migration +``` + +## View Terraform Enterprise application version + +This command retrieves the currently running version of Terraform Enterprise: + +```shell-session +$ tfectl app version +``` + +## Mounted disk commands + + + These commands are not relevant if you manage your own database instance or run Terraform Enterprise with an external database. + + +When using `TFE_OPERATIONAL_MODE: disk`, Terraform Enterprise runs its Postgres instance managed through the container. +Admin CLI provides commands for common operations. + +### Create a database backup + +To create backups of the internal database instance, use the following command: + +```shell-session +$ tfectl db backup +``` + +This command will generate the backup in the directory passed via the environment variable `TFE_DISK_PATH`, default `/var/lib/terraform-enterprise`. +The backup filename will be created in the format `TIMESTAMP_hashicorp.db`. ` + +You can specify the backup's destination via the `--out` flag, e.g. + +```shell-session +$ tfectl db backup --out /path/to/backup.db +``` + +### Recreate database indices + +Rebuild Postgres database indices using: + +```shell-session +$ tfectl db reindex +``` + +### Restore database from a backup + +* The execution of this command will **momentarily shut down your Terraform Enterprise instance**. Please make sure that no work +is being executed, and no one is using the instance before running this command. After the restore takes place, Atlas +will come back online. + +* This operation is **irreversible**, once a database backup has been loaded, all data created between the time of the +backup and the date of restoration **will be lost**. + +To restore a database from a backup file, run: + +```shell-session +$ tfectl db restore --file /path/to/backup.db +``` + +Confirmation is needed, with only `yes` as a valid response. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/configuration.mdx new file mode 100644 index 0000000000..559e48368e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/configuration.mdx @@ -0,0 +1,748 @@ +--- +page_title: Terraform Enterprise configuration reference +description: >- + Learn about the configuration options for deploying Terraform Enterprise. +--- + +# Terraform Enterprise configuration reference + +This topic contains reference information about the configurations you can specify for Terraform Enterprise. + +## Introduction + +Specify environment variables to configure the operational mode, connections to external systems, and other settings. Specify the variables in a configuration file for your runtime environment, such as a +[Docker Compose file](https://docs.docker.com/compose/compose-file/03-compose-file/), Kubernetes [Helm chart](https://helm.sh/), or in the `env` block of your [Nomad job](/nomad/docs/job-specification/env). Refer to [Create deployment configuration overview](/terraform/enterprise/deploy/configuration) for additional information. + + +## Application settings + +### `TFE_CAPACITY_CONCURRENCY` + +Maximum number of Terraform runs that can execute concurrently on each +Terraform Enterprise node. Defaults to `10`. + +### `TFE_CAPACITY_CPU` + +Maximum number of CPU cores a Terraform run is allowed to use. Set to `0` for +no limit. Defaults to `0`. +Ignored if `TFE_RUN_PIPELINE_DRIVER` is set to `nomad`. + +### `TFE_CAPACITY_MEMORY` + +Maximum amount of memory (MiB) a Terraform run is allowed to use. Defaults to +`2048`. +Ignored if `TFE_RUN_PIPELINE_DRIVER` is set to `nomad`. + +### `TFE_ENCRYPTION_PASSWORD` + +Encryption password used to encrypt and decrypt the internal Vault root token +and unseal key. + +Required when `TFE_VAULT_USE_EXTERNAL` is `false`. + +### `TFE_HOSTNAME` + +Hostname where Terraform Enterprise is accessed (e.g., +`terraform.example.com`). + +Required always. + +### `TFE_HOSTNAME_SECONDARY` + +Specifies a secondary hostname for Terraform Enterprise. You can use this setting for external-facing endpoints, such as OIDC workload identity federation. This hostname must be externally resolvable and configured with appropriate DNS and TLS settings, for example `tfe-external.example.com`. + + Refer to [Configure network access](/terraform/enterprise/deploy/configuration/network) for additional information. + + +### `TFE_LICENSE` + +The raw HashiCorp license (e.g., `02MV4UU4...MSEKE6T2`). Defaults to `""`. + +Required when `TFE_LICENSE_PATH` is unset. + +### `TFE_LICENSE_PATH` + +Path to a file containing the raw HashiCorp license. Must be mounted inside the +container (e.g., `/opt/terraform-enterprise-license`). Defaults to `""`. + +Required when `TFE_LICENSE` is unset. + +### `TFE_LICENSE_REPORTING_OPT_OUT` + +Whether to opt out of reporting licensing information to HashiCorp. Defaults to `false`. + +### `TFE_USAGE_REPORTING_OPT_OUT` + +Whether to opt out of reporting usage information to HashiCorp. Defaults to `false`. + +### `TFE_RUN_PIPELINE_DRIVER` + +Driver for Terraform runs. Must be one of `nomad`, `docker` or `kubernetes`. Defaults to +`docker`. +If set to `nomad`, the `TFE_CAPACITY_CPU` and `TFE_CAPACITY_MEMORY` settings are ignored. + +Required for all deployment options. + +### `TFE_OPERATIONAL_MODE` + +Determines how Terraform Enterprise stores and retrieves data. This variable is required for all runtimes except Kubernetes. + +You can set one of the following values: + +- `disk`: Runs Terraform Enterprise, PostgreSQL database, optional Redis data store, and S3-compatible storage in the same container. In this mode, Terraform Enterprise manages the storage objects. By default, this mode limits the number of Terraform Enterprise instances to one. +- `external`: Runs Terraform and optional Redis store in the same container. In this mode, Terraform Enterprise can manage the Redis store, but you are responsible for managing the PostgreSQL database and S3-compatible storage as external services. By default, this mode limits the number of Terraform Enterprise instances to one. +- `active-active`: Runs Terraform Enterprise in its own container. In this mode, you are responsible for managing the PostgreSQL, optional Redis data store, and S3-compatible storage as external services. As a result, you can deploy more than one instance of Terraform Enterprise. Terraform Enterprise operates in `active-active` mode when it is deployed to Kubernetes. + +Refer to [Configure the operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) for additional information. + +### `TFE_RUN_PIPELINE_IMAGE` + +Container image used to execute Terraform runs. Leave blank to use the default +image that comes with Terraform Enterprise. Defaults to `""`. + +### `TFE_DISK_PATH` + +Path where Terraform Enterprise stores application data. Must be backed by +persistent and performant storage such as a container volume or block storage. +Defaults to `/var/lib/terraform-enterprise`. + +Required when `TFE_OPERATIONAL_MODE` is `disk` on Docker runtime. + +### `TFE_BACKUP_RESTORE_TOKEN` + +The authentication token for the backup/restore API. Leave blank to have it be automatically generated. Defaults to `""`. + +### `TFE_HTTP_PORT` + +Port application listens on for HTTP. Default `80`. + +### `TFE_HTTPS_PORT` + +Port application listens to HTTPS on. Default `443`. + +## Database settings + +### `TFE_DATABASE_HOST` + +The PostgreSQL server to connect to in the format `HOST[:PORT]` (e.g., +`db.example.com` or `db.example.com:5432`). If only `HOST` is provided then the +`:PORT` defaults to `:5432`. + +Required when connecting to an external PostgreSQL server. + +### `TFE_DATABASE_NAME` + +Name of the PostgreSQL database to store application data in. + +Required when connecting to an external PostgreSQL server. + +### `TFE_DATABASE_PARAMETERS` + +PostgreSQL server parameters for the connection URI. Used to configure the +PostgreSQL connection (e.g., `sslmode=require`). + +### `TFE_DATABASE_PASSWORD` + +PostgreSQL password. + +Required when connecting to an external PostgreSQL server without client certificates. + +### `TFE_DATABASE_USER` + +PostgreSQL user. + +Required when connecting to an external PostgreSQL server. + +### `TFE_DATABASE_RECONNECT_ENABLED` + +Enables Terraform Enterprise to reconnect to the database when the database connection is interrupted. We recommend setting to `true` when connecting to an external PostgreSQL cluster. Refer to [Connect to a PostgreSQL cluster ](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres-cluster) for additional information. + +This setting is not applicable for Replicated. + +Defaults is `false`. + +### `TFE_DATABASE_USE_MTLS` + +Whether to use mTLS while authenticating with the PostgreSQL server. When mTLS is enabled, Terraform Enterprise uses client certificates to authenticate with the PostgreSQL server. +Terraform Enterprise requires PostgreSQL server certificate to use Subject Alternative Names (SANs) rather than relying solely on the legacy Common Name field. + +Defaults to `false`. + +### `TFE_DATABASE_CA_CERT_FILE` + +Specifies the path to a file containing the root certificate for validating PostgreSQL server certificates. +Defaults to `""`. + +Required when `TFE_DATABASE_USE_MTLS` is `true`. + +### `TFE_DATABASE_CLIENT_CERT_FILE` + +Specifies the path to a file containing the client certificate that Terraform Enterprise uses for authenticating with the PostgreSQL server. +Defaults to `""`. + +Required when `TFE_DATABASE_USE_MTLS` is `true`. + +### `TFE_DATABASE_CLIENT_KEY_FILE` + +Specifies the path to a file containing the client private key corresponding to the PostgreSQL client certificate provided in `TFE_DATABASE_CLIENT_CERT_FILE`. +Defaults to `""`. + +Required when `TFE_DATABASE_USE_MTLS` is `true`. + +## Redis settings + +### `TFE_REDIS_HOST` + +The Redis server to connect to in the format `HOST[:PORT]` (e.g., +`redis.example.com` or `redis.example.com:`). If only `HOST` is provided then +the `:PORT` defaults to `:6379`. + +Required when Redis server is externalized. + +### `TFE_REDIS_USE_AUTH` + +Must be `true` or `false`. `true` indicates Redis server is configured to use `TFE_REDIS_PASSWORD` and `TFE_REDIS_USER` (optional) for authentication. Defaults to `false`. + +### `TFE_REDIS_USE_TLS` + +Must be `true` or `false`. `true` indicates to use TLS to access Redis. Defaults to `false`. + +### `TFE_REDIS_USER` + +Redis server user. This value is required when `TFE_REDIS_USE_AUTH` is set to `true`, and Redis server is configured to use username for authentication. There is no need to set this config when running Redis server internally as credential is not required. + +### `TFE_REDIS_PASSWORD` + +Redis server password. This value is required when `TFE_REDIS_USE_AUTH` is set to `true`. There is no need to set this config when running Redis server internally as credential is not required. + +### `TFE_REDIS_SIDEKIQ_HOST` + +The Redis server to connect to in the format `HOST[:PORT]` (e.g., +`redis.example.com` or `redis.example.com:`). If only `HOST` is provided then +the `:PORT` defaults to `:6379`. + +Required when Redis server is externalized and Redis Enterprise is the external +service target. + +### `TFE_REDIS_SIDEKIQ_USE_AUTH` + +Must be `true` or `false`. `true` indicates Redis server is configured to use `TFE_REDIS_SIDEKIQ_PASSWORD` and `TFE_REDIS_SIDEKIQ_USER` (optional) for authentication. Defaults to `false`. + +### `TFE_REDIS_SIDEKIQ_USE_TLS` + +Must be `true` or `false`. `true` indicates to use TLS to access Redis. Defaults to `false`. + +### `TFE_REDIS_SIDEKIQ_USER` + +Redis server user. This value is required when `TFE_REDIS_SIDEKIQ_USE_AUTH` is set to `true`, and Redis server is configured to use username for authentication. There is no need to set this config when running Redis server internally as credential is not required. + +### `TFE_REDIS_SIDEKIQ_PASSWORD` + +Redis server password. This value is required when `TFE_REDIS_SIDEKIQ_USE_AUTH` is set to `true`. There is no need to set this config when running Redis server internally as credential is not required. + +### `TFE_REDIS_SENTINEL_ENABLED` + +Must be `true` or `false`. `true` indicates Redis Sentinel is configured. Defaults to `true`. + +### `TFE_REDIS_SENTINEL_HOSTS` + +Specifies one or more Redis Sentinel server addresses to connect to using the `HOST:PORT` format. The port number is optional and defaults to `:26379` when only the host address is provided. + +The following example specifies two servers. The first server uses the default port number. The second server is configured to explicitly listen on port `26379`: + +```yaml +TFE_REDIS_SENTINEL_HOSTS: redis-sentinel-1.example.com,redis-sentinel-2.example.com:26379 +``` + +Required when `TFE_REDIS_SENTINEL_ENABLED` is set to `true`. + +### `TFE_REDIS_SENTINEL_LEADER_NAME` + +The name of a Redis Sentinel master such as `main`. This name should return a valid Redis service location when issuing +a `SENTINEL GET-MASTER-ADDR-BY-NAME ` command to Redis Sentinel. + +Required when `TFE_REDIS_SENTINEL_ENABLED` is set to `true`. + +### `TFE_REDIS_SENTINEL_USERNAME` + +Redis Sentinel server user. + +### `TFE_REDIS_SENTINEL_PASSWORD` + +Redis Sentinel server password. + +## Initial admin creation token + +### `TFE_IACT_TOKEN` +A pre-populated initial admin creation token. If you do not set this value, a random one will be generated for you. + +### `TFE_IACT_SUBNETS` + +Comma-separated list of subnets in CIDR notation that are allowed to retrieve +the initial admin creation token via the API (e.g., +`10.0.0.0/8,192.168.0.0/24`). Leave blank to disable retrieving the initial +admin creation token via the API from outside the host. Defaults to +`""`. + +If you do not set this value, you must gain access to the container or pod command line and run `curl http://localhost:80/admin/retrieve-iact` to retrieve the initial admin token. + +### `TFE_IACT_TIME_LIMIT` + +Number of minutes that the initial admin creation token can be retrieved via +the API after the application starts. Defaults to `60`. + +### `TFE_IACT_TRUSTED_PROXIES` + +Comma-separated list of proxy IP addresses that are allowed to retrieve the initial admin creation token via the API. Leave blank to disable retrieving the initial admin creation token through a proxy. Defaults to `""`. + +## Network settings + +### `http_proxy` +Configures the proxy address to use for HTTP requests, for example`http://proxy.example.com:8080`. Do not set a value blank to disable using a proxy server. Defaults to `""`. + +### `https_proxy` +Configures the proxy address to use for HTTPS requests, for example `http://proxy.example.com:8080`. Leave blank to disable using a proxy server. Defaults to `""`. + +### `no_proxy` +Specifies a list of domains that instances, such as S3, are allowed to connect directly to without going through the proxy, for example `localhost,127.0.0.1`. Defaults to `""`. +When defining a proxy, this should include following addresses `127.0.0.1,localhost,,` but is not limited to. + +### `TFE_OIDC_HOSTNAME_CHOICE` + +Specifies which hostname Terraform Enterprise should use to federate OIDC workloads for OIDC-related integrations. You can specify one of the following values: + +- `primary`: Terraform Enterprise uses the hostname specified in the [`TFE_HOSTNAME`](#tfe_hostname) setting. +- `secondary`: Terraform Enterprise uses the hostname specified in the [`TFE_HOSTNAME`](#tfe_hostname_secondary) setting. + +Default is `primary`. + +### `TFE_VCS_HOSTNAME_CHOICE` + +Specifies which hostname Terraform Enterprise should use to federate version control system (VCS) workloads for VCS-related integrations. You can specify one of the following values: + +- `primary`: Terraform Enterprise uses the hostname specified in the `TFE_HOSTNAME` setting. +- `secondary`: Terraform Enterprise uses the hostname specified in the `TFE_HOSTNAME_SECONDARY` setting. + +You must set up new VCS connections if you update the `TFE_VCS_HOSTNAME_CHOICE` configuration. When `TFE_VCS_HOSTNAME_CHOICE` is set to `secondary`, you should continue using the secondary hostname while setting up the new VCS connection. When setup is complete, you can use the primary hostname for all other activities. + +Refer to [Configure a VCS host for Terraform Enterprise](/terraform/enterprise/vcs#configure-a-vcs-host-for-terraform-enterprise) for additional information. + +Default is `primary`. + +### `TFE_RUN_TASK_HOSTNAME_CHOICE` + +Specifies which hostname Terraform Enterprise should use to federate run task workloads for custom integrations. You can specify one of the following values: + +- `primary`: Terraform Enterprise uses the hostname specified in the `TFE_HOSTNAME` setting. +- `secondary`: Terraform Enterprise uses the hostname specified in the `TFE_HOSTNAME_SECONDARY` setting. + +Default is `primary`. + +## Observability settings + +### `TFE_LOG_FORWARDING_CONFIG_PATH` + +The path to a file containing valid Fluent Bit `[OUTPUT]` configuration. The +contents of the file you specify are appended to your existing Fluent Bit +configuration if you set `TFE_LOG_FORWARDING_ENABLED` to `true`. +Refer to [Enable log forwarding](/terraform/enterprise/deploy/manage/monitor#enable-log-forwarding) +for more information. + +This setting is not applicable for Kubernetes. + +### `TFE_LOG_FORWARDING_ENABLED` + +Whether to enable log forwarding. Defaults to `false`. + +This setting is not applicable for Kubernetes. + +### `TFE_METRICS_ENABLE` + +Whether to enable metrics collection. Defaults to `false`. + +### `TFE_METRICS_HTTP_PORT` + +The HTTP port that metrics will be exposed on. Defaults to `9090`. + +### `TFE_METRICS_HTTPS_PORT` + +The HTTPS port that metrics will be exposed on. Defaults to `9091`. + +## Object storage settings + +### `TFE_OBJECT_STORAGE_TYPE` + +Type of object storage to use. Must be one of `s3`, `azure`, or `google`. + +Required when object storage is externalized. + +### Azure blob Storage settings + +#### `TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY` + +Azure Blob Storage access key. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `azure` and +`TFE_OBJECT_STORAGE_AZURE_USE_MSI` is `false`. + +#### `TFE_OBJECT_STORAGE_AZURE_ACCOUNT_NAME` + +Azure Blob Storage account name. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `azure`. + +#### `TFE_OBJECT_STORAGE_AZURE_CLIENT_ID` + +Client ID of a user-assigned Managed Service Identity. Leave blank to use the +system-assigned Managed Service Identity. Defaults to `""`. + +#### `TFE_OBJECT_STORAGE_AZURE_CONTAINER` + +Azure Blob Storage container name. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `azure`. + +#### `TFE_OBJECT_STORAGE_AZURE_ENDPOINT` + +Azure Storage endpoint. Useful if using a private endpoint for Azure Storage. +Leave blank to use the default Azure Storage endpoint. Defaults to `""`. + +#### `TFE_OBJECT_STORAGE_AZURE_USE_MSI` + +Whether to use Managed Service Identity (MSI) for authentication. Defaults to +`false`. + +### Google Cloud Platform storage + +#### `TFE_OBJECT_STORAGE_GOOGLE_BUCKET` + +Google Cloud Storage bucket name. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `google`. + +#### `TFE_OBJECT_STORAGE_GOOGLE_CREDENTIALS` + +Google Cloud Storage JSON credentials. Must be given as an escaped string of +JSON or Base64 encoded JSON. Leave blank to use the attached service account. +Defaults to `""`. + +#### `TFE_OBJECT_STORAGE_GOOGLE_PROJECT` + +Google Cloud Storage project name. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `google`. + +### S3-compatible Storage + +#### `TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID` + +S3 access key ID. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `s3` and +`TFE_OBJECT_STORAGE_S3_USE_INSTANCE_PROFILE` is `false`. + +#### `TFE_OBJECT_STORAGE_S3_BUCKET` + +S3 bucket name. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `s3`. + +#### `TFE_OBJECT_STORAGE_S3_ENDPOINT` + +S3 endpoint. Useful when using a private S3 endpoint. Leave blank to use the +default AWS S3 endpoint. Defaults to `""`. + +#### `TFE_OBJECT_STORAGE_S3_REGION` + +S3 region. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `s3`. + +#### `TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY` + +S3 secret access key. + +Required when `TFE_OBJECT_STORAGE_TYPE` is `s3` and +`TFE_OBJECT_STORAGE_S3_USE_INSTANCE_PROFILE` is `false`. + +#### `TFE_OBJECT_STORAGE_S3_SERVER_SIDE_ENCRYPTION` + +Server-side encryption algorithm to use. Leave blank to have the AWS SDK use a +default value. Set to `AES256` to use AES-256 encryption, the AWS S3 default +since January 5, 2023. Set to `aws:kms` to use an AWS KMS key to encrypt data +in which case you must specify +`TFE_OBJECT_STORAGE_S3_SERVER_SIDE_ENCRYPTION_KMS_KEY_ID`. Defaults to `""`. + +#### `TFE_OBJECT_STORAGE_S3_SERVER_SIDE_ENCRYPTION_KMS_KEY_ID` + +KMS key ID to use for server-side encryption. Leave blank to use AWS-managed +keys. Defaults to `""`. + +#### `TFE_OBJECT_STORAGE_S3_USE_INSTANCE_PROFILE` + +Whether to use the default AWS credential chain for authentication. When set to `true`, Terraform Enterprise attempts to authenticate to AWS using the following workload identities: + +- EC2 IAM instance profile +- IAM roles for Kubernetes service accounts (IRSA) +- EKS pod identity + +Defaults to `false`. + +#### `TFE_OBJECT_STORAGE_S3_UPLOAD_PART_SIZE` + +Optional configuration of the size of the data packets sent to S3. Defaults to `1024` if left blank. + + +#### `TFE_OBJECT_STORAGE_S3_UPLOAD_CONCURRENCY` + +Optional configuration of the concurrency when sending data to S3. Defaults to `3` if left blank. + +## TLS settings + +### `TFE_TLS_CA_BUNDLE_FILE` + +Path to a file containing TLS CA certificates to be added to the OS CA +certificates bundle. Leave blank to not add CA certificates to the OS CA +certificates bundle. Defaults to `""`. + +### `TFE_TLS_CERT_FILE` + +Path to a file containing the TLS certificate Terraform Enterprise will use +when serving TLS connections to clients. + +Required always. + +### `TFE_TLS_CERT_FILE_SECONDARY` + +Specifies the path to the TLS certificate file used for the secondary hostname, for example `/etc/ssl/private/terraform-enterprise/ext_cert.pem`. + +Configure this setting to secure HTTPS connections for external integrations using the secondary hostname. + +This settings is required when [`TFE_HOSTNAME_SECONDARY`](#tfe_hostname_secondary) is set. + +### `TFE_TLS_CIPHERS` + +TLS ciphers to use for TLS. Must be valid OpenSSL format. Leave blank to use +the default ciphers. Defaults to `""`. + +### `TFE_TLS_ENFORCE` + +Whether or not to enforce TLS, Strict-Transport-Security headers, and secure +cookies. Defaults to `false`. + +### `TFE_TLS_KEY_FILE` + +Path to a file containing the TLS private key Terraform Enterprise will use +when serving TLS connections to clients. + +### `TFE_TLS_KEY_FILE_SECONDARY` + +Specifies the path to the TLS private key file used for the secondary hostname, for example `/etc/ssl/private/terraform-enterprise/ext_key.pem`. + +You must also configure the [`TFE_TLS_CERT_FILE_SECONDARY`](#tfe_tls_cert_file_secondary) setting to enable secure HTTPS connections. + +This settings is required when [`TFE_HOSTNAME_SECONDARY`](#tfe_hostname_secondary) is set. + +### `TFE_TLS_VERSION` + +TLS version to use. Must be one of `tls_1_2`, `tls_1_3`, or blank. Leave blank +to use both TLS v1.2 and TLS v1.3. Defaults to `""`. + +## Vault settings + +### `TFE_VAULT_ADDRESS` + +Address of the external Vault server (e.g., https://vault.example.com:8200). +Defaults to `""`. + +Required when `TFE_VAULT_USE_EXTERNAL` is `true`. + +### `TFE_VAULT_CLUSTER_ADDRESS` + +Cluster URL of the internal Vault server on this node (e.g., +http://192.168.0.1:8201). Must be reachable across nodes. Defaults to +`http://{{ GetPrivateIP }}:8201`. + +Required when `TFE_OPERATIONAL_MODE` is `active-active`. + +### `TFE_VAULT_DISABLE_MLOCK` + +Disable mlock for internal Vault. Defaults to `false`. + +### `TFE_VAULT_NAMESPACE` + +Vault namespace. External Vault only. Leave blank to use the default namespace. +Defaults to `""`. + +### `TFE_VAULT_PATH` + +Vault path when AppRole is mounted. External Vault only. Defaults to +`auth/approle`. + +### `TFE_VAULT_ROLE_ID` + +Vault role ID. External Vault only. + +Required when `TFE_VAULT_USE_EXTERNAL` is `true`. + +### `TFE_VAULT_SECRET_ID` + +Vault secret ID. External Vault only. + +Required when `TFE_VAULT_USE_EXTERNAL` is `true`. + +### `TFE_VAULT_TOKEN_RENEW` + +How often, in seconds, to renew the Vault token. External Vault only. Defaults +to `3600`. + +### `TFE_VAULT_USE_EXTERNAL` + +Whether to use external Vault. Defaults to `false`. + +## Docker driver settings + +### `TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS` + +Comma-separated list of extra hosts in the format `HOST:IP,HOST:IP` to set in +the `/etc/hosts` file within the container used to execute Terraform runs. +Leave blank to not set any extra hosts. Defaults to `""`. + +### `TFE_RUN_PIPELINE_DOCKER_NETWORK` + +Network where the container used to execute Terraform runs will be created. The +network must already exist, it will not be created automatically. Leave blank +to use the default network. Defaults to `""`. + +### `TFE_DISK_CACHE_PATH` + +Path where Terraform Enterprise caches Terraform binaries. The volume specified +in `TFE_DISK_CACHE_VOLUME_NAME` must be mounted to this path. Defaults to +`/var/cache/tfe-task-worker`. + +Required when `TFE_RUN_PIPELINE_DRIVER` is `docker`. + +### `TFE_DISK_CACHE_VOLUME_NAME` + +Container volume name backing the `TFE_DISK_CACHE_PATH`. + +Required when `TFE_RUN_PIPELINE_DRIVER` is `docker`. + +## Kubernetes driver settings + +### `TFE_RUN_PIPELINE_KUBERNETES_IMAGE_PULL_SECRET_NAME` + +The name of an ImagePullSecret in the [namespace]-agents namespace to use when pulling the custom source tfc-agent image. If an ImagePullSecret is required to access a private repository you must create the secret within the [namespace]-agents namespace after this helm chart has installed, but before attempting a plan or apply. See Prerequisites for instructions for creating ImagePullSecrets. + +### `TFE_RUN_PIPELINE_KUBERNETES_KUBECONFIG_PATH` + +The path to a Kubernetes configuration file. + +### `TFE_RUN_PIPELINE_KUBERNETES_NAMESPACE` + +The Kubernetes namespace to create ephemeral run containers. Defaults to +`default`. + +### `TFE_RUN_PIPELINE_KUBERNETES_OPEN_SHIFT_ENABLED` + +A feature toggle to enable or disable compatibility with an OpenShift runtime +environment. Defaults to `false`. + +### `TFE_RUN_PIPELINE_KUBERNETES_DEBUG_ENABLED` + +Boolean flag that will delay the deletion of jobs from the cluster for their inspection. + +### `TFE_RUN_PIPELINE_KUBERNETES_DEBUG_JOBS_TTL` + +Time in seconds after which the jobs delayed by the `TFE_RUN_PIPELINE_KUBERNETES_DEBUG_ENABLED` flag will get deleted. Defaults to 86400, 1 day. + +### `TFE_RUN_PIPELINE_KUBERNETES_POD_TEMPLATE` + +This is a base64-encoded custom pod template in JSON format, equivalent to Kubernetes' `corev1.PodTemplateSpec`, used in a job. The values here will override corresponding values from Terraform Enterprise configuration. Note that only one container is allowed in the pod template. + +### `TFE_RUN_PIPELINE_KUBERNETES_WORKER_TIMEOUT` + +Time in seconds after which Terraform Enterprise will fails jobs submitted to Kubernetes. Defaults to `60`. + +## Nomad driver settings + +### `TFE_RUN_PIPELINE_NOMAD_NAMESPACE` + +The Nomad namespace where Terraform Enterprise agent job starts. Defaults to `tfe-agents`. + +### `TFE_RUN_PIPELINE_NOMAD_AGENT_JOB_ID` + +Specifies the ID of the batch job that runs the Terraform Enterprise agent. Defaults to `tfe-agent-job`. + +### `TFE_RUN_PIPELINE_NOMAD_WORKER_TIMEOUT` + +Max timeout in seconds used by Terraform Enterprise workers to connect with Nomad and start an agent job. Defaults to `60`. + +## Proxy configuration + +Terraform Enterprise relies on the native application runtime for setting proxy values. For configuring proxies in Docker, +refer to the official [Docker proxy configuration guide](https://docs.docker.com/network/proxy/). For Kubernetes, refer to the +[Kubernetes proxy configuration guide](https://kubernetes.io/docs/concepts/cluster-administration/proxies/). For Nomad deployments, refer to the [reference architecture guide](/terraform/enterprise/deploy/replicated/architecture/reference-architecture) + +## Replicated to flexible deployments configuration mapping + +The following table describes how the Replicated configuration maps to the configuration settings for non-Replicated deployments. Refer to [settings](#application-settings) for more information about the variables. + +| Replicated | Non-Replicated | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| aws_access_key_id | [TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID](#tfe_object_storage_s3_access_key_id) | +| aws_instance_profile | [TFE_OBJECT_STORAGE_S3_USE_INSTANCE_PROFILE](#tfe_object_storage_s3_use_instance_profile) | +| aws_secret_access_key | [TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY](#tfe_object_storage_s3_secret_access_key) | +| azure_account_key | [TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY](#tfe_object_storage_azure_account_key) | +| azure_account_name | [TFE_OBJECT_STORAGE_AZURE_ACCOUNT_NAME](#tfe_object_storage_azure_account_name) | +| azure_client_id | [TFE_OBJECT_STORAGE_AZURE_CLIENT_ID](#tfe_object_storage_azure_client_id) | +| azure_container | [TFE_OBJECT_STORAGE_AZURE_CONTAINER](#tfe_object_storage_azure_container) | +| azure_endpoint | [TFE_OBJECT_STORAGE_AZURE_ENDPOINT](#tfe_object_storage_azure_endpoint) | +| azure_use_msi | [TFE_OBJECT_STORAGE_AZURE_USE_MSI](#tfe_object_storage_azure_use_msi) | +| backup_token | [TFE_BACKUP_RESTORE_TOKEN](#tfe_backup_restore_token) | +| capacity_concurrency | [TFE_CAPACITY_CONCURRENCY](#tfe_capacity_concurrency) | +| capacity_cpus | [TFE_CAPACITY_CPU](#tfe_capacity_cpu) | +| capacity_memory | [TFE_CAPACITY_MEMORY](#tfe_capacity_memory) | +| custom_agent_image_tag | [TFE_RUN_PIPELINE_IMAGE](#tfe_run_pipeline_image) | +| disk_path | [TFE_DISK_PATH](#tfe_disk_path) | +| enable_active_active | [TFE_OPERATIONAL_MODE](#tfe_operational_mode) | +| enc_password | [TFE_ENCRYPTION_PASSWORD](#tfe_encryption_password) | +| extern_vault_addr | [TFE_VAULT_ADDRESS](#tfe_vault_address) | +| extern_vault_namespace | [TFE_VAULT_NAMESPACE](#tfe_vault_namespace) | +| extern_vault_path | [TFE_VAULT_PATH](#tfe_vault_path) | +| extern_vault_role_id | [TFE_VAULT_ROLE_ID](#tfe_vault_role_id) | +| extern_vault_secret_id | [TFE_VAULT_SECRET_ID](#tfe_vault_secret_id) | +| extern_vault_token_renew | [TFE_VAULT_TOKEN_RENEW](#tfe_vault_token_renew) | +| force_tls | [TFE_TLS_ENFORCE](#tfe_tls_enforce) | +| gcs_bucket | [TFE_OBJECT_STORAGE_GOOGLE_BUCKET](#tfe_object_storage_google_bucket) | +| gcs_credentials | [TFE_OBJECT_STORAGE_GOOGLE_CREDENTIALS](#tfe_object_storage_google_credentials) | +| gcs_project | [TFE_OBJECT_STORAGE_GOOGLE_PROJECT](#tfe_object_storage_google_project) | +| hostname | [TFE_HOSTNAME](#tfe_hostname) | +| iact_subnet_list | [TFE_IACT_SUBNETS](#tfe_iact_subnets) | +| iact_subnet_time_limit | [TFE_IACT_TIME_LIMIT](#tfe_iact_time_limit) | +| log_forwarding_config | [TFE_LOG_FORWARDING_CONFIG_PATH](#tfe_log_forwarding_config_path) | +| log_forwarding_enabled | [TFE_LOG_FORWARDING_ENABLED](#tfe_log_forwarding_enabled) | +| metrics_endpoint_enabled | [TFE_METRICS_ENABLE](#tfe_metrics_enable) | +| metrics_endpoint_port_http | [TFE_METRICS_HTTP_PORT](#tfe_metrics_http_port) | +| metrics_endpoint_port_https | [TFE_METRICS_HTTPS_PORT](#tfe_metrics_https_port) | +| optout_license_reporting | [TFE_LICENSE_REPORTING_OPT_OUT](#tfe_license_reporting_opt_out) | +| optout_usage_reporting | [TFE_USAGE_REPORTING_OPT_OUT](#tfe_usage_reporting_opt_out) | +| pg_dbname | [TFE_DATABASE_NAME](#tfe_database_name) | +| pg_extra_params | [TFE_DATABASE_PARAMETERS](#tfe_database_parameters) | +| pg_netloc | [TFE_DATABASE_HOST](#tfe_database_host) | +| pg_password | [TFE_DATABASE_PASSWORD](#tfe_database_password) | +| pg_user | [TFE_DATABASE_USER](#tfe_database_user) | +| placement | [TFE_OBJECT_STORAGE_TYPE](#tfe_object_storage_type) | +| production_type | [TFE_OPERATIONAL_MODE](#tfe_operational_mode) | +| redis_host | [TFE_REDIS_HOST](#tfe_redis_host) | +| redis_pass | [TFE_REDIS_PASSWORD](#tfe_redis_password) | +| redis_port | [TFE_REDIS_HOST](#tfe_redis_host) | +| redis_use_password_auth | [TFE_REDIS_USE_AUTH](#tfe_redis_use_auth) | +| redis_use_tls | [TFE_REDIS_USE_TLS](#tfe_redis_use_tls) | +| s3_bucket | [TFE_OBJECT_STORAGE_S3_BUCKET](#tfe_object_storage_s3_bucket) | +| s3_endpoint | [TFE_OBJECT_STORAGE_S3_ENDPOINT](#tfe_object_storage_s3_endpoint) | +| s3_region | [TFE_OBJECT_STORAGE_S3_REGION](#tfe_object_storage_s3_region) | +| s3_sse | [TFE_OBJECT_STORAGE_S3_SERVER_SIDE_ENCRYPTION](#tfe_object_storage_s3_server_side_encryption) | +| s3_sse_kms_key_id | [TFE_OBJECT_STORAGE_S3_SERVER_SIDE_ENCRYPTION_KMS_KEY_ID](#tfe_object_storage_s3_server_side_encryption_kms_key_id) | +| tls_ciphers | [TFE_TLS_CIPHERS](#tfe_tls_ciphers) | +| tls_vers | [TFE_TLS_VERSION](#tfe_tls_version) | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/data-security.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/data-security.mdx new file mode 100644 index 0000000000..caa44683f4 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/data-security.mdx @@ -0,0 +1,8 @@ +--- +page_title: Terraform Enterprise data security reference +description: >- + Terraform Enterprise objects may contain sensitive data. Learn about storage + and encryption methods Terraform Enterprise uses to protect sensitive data. +--- + +@include "replicated-and-fdo/architecture/data-security-partial.mdx" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/license-data.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/license-data.mdx new file mode 100644 index 0000000000..0c150673aa --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/license-data.mdx @@ -0,0 +1,66 @@ +--- +page_title: License report reference +description: Learn about the license usage information HashiCorp collects in order to meter license consumption in your organization. +--- + +# License report reference + +By default, Terraform Enterpise automatically sends license usage metrics to HashiCorp. Refer to [Enable automated license utilization reporting](/terraform/enterprise/deploy/manage/license-report) for additional information. HashiCorp collects the following data as a JSON payload: + +- `payload_version`: The version of this payload schema +- `license_id`: The license ID for this product +- `product`: The product that this contribution is for +- `product_version`: The product version this contribution is for +- `export_timestamp`: The date and time for this contribution + - `snapshots`: An array of snapshot details. A snapshot is a structure that represents a single data collection. + - `snapshot_version`: The version of the snapshot package that produced this snapshot + - `snapshot_id`: A unique identifier for this particular snapshot + - `process_id`: An identifier for the system that produced this snapshot + - `timestamp`: The date and time for this snapshot + - `schema_version`: The version of the schema associated with this snapshot + - `service`: The service that produced this snapshot (likely to be product name) + - `metrics`: A map of representations of snapshot metrics contained within this snapshot + - `key`: The key name associated with this metric + - `workspacecount`: Total number of workspaces defined in the Terraform Enterprise instance + - `kind`: The kind of metric (feature, counter, sum, or mean) + - `mode`: The mode of operation associated with this metric (write or collect) + - `value`: The value of the metric at the time the licensing exporter took this snapshot +- `metadata`: Optional product-specific metadata + - `replicated_license_id`: The unique ID of the Replicated license. When deployed to a non-Replicated runtime, this field returns empty. + - `sf_opportunity_id`: The Salesforce opportunity ID associated with the license. When deployed to a non-Replicated runtime, this field returns empty. + +## Example payload + +```json +{ + "payload_version": "1", + "license_id": "934b62bd-7e7b-7872-7341-9683ecd9acb4", + "product": "terraform", + "product_version": "v202305-01", + "export_timestamp": "2023-05-24T10:11:12Z", + "snapshots": [ + { + "snapshot_version": 1, + "snapshot_id": "01GW2Y117Z2BZ7MGS9YQXPF2A4", + "process_id": "01GVKT7533WF8TBNSJYZV0T10F", + "timestamp": "2023-05-23T20:33:32.927Z", + "schema_version": "1.0.0", + "service": "terraform", + "metrics": { + "terraform.workspacecount": { + "key": "terraform.workspacecount", + "kind": "counter", + "mode": "write", + "value": 20 + } + } + } + ], + "metadata": { + "terraform": { + "replicated_license_id": "vi15fg2ysml54yhhd8evcfjl63h6pt6k", + "sf_opportunity_id": "ix0z0kj5f7egd64bo1" + } + } +} +``` \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/metrics.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/metrics.mdx new file mode 100644 index 0000000000..1481d5d5bf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/metrics.mdx @@ -0,0 +1,70 @@ +--- +page_title: Container metrics reference +description: >- + Learn about the metrics that are exposed by Terraform Enterprise. +--- + +# Container metrics reference + +This topic provides reference information about the metrics that Terraform Enterprise can expose when enabled. Refer to [Monitor Terraform Enterprise](/terraform/enterprise/deploy/manage/monitor) for instructions on how to enable metrics. + +## Container metrics + +The following table describes metrics report runtime information about Terraform Enterprise containers. + +| Exposed Metric | Metrics Type | Description | +| ----------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | +| `tfe.container.cpu.usage.user` | `counter` | Running count, in nanoseconds, of the total amount of time processes in the container have spent in userspace | +| `tfe.container.cpu.usage.kernel` | `counter` | Running count, in nanoseconds, of the total amount of time processes in the container have spent in kernel space | +| `tfe.container.memory.used_bytes` | `gauge` | The amount of memory allocated to the container in bytes, minus memory that is used for page cache | +| `tfe.container.memory.limit` | `gauge` | The maximum amount of memory in bytes that can be allocated by the container | +| `tfe.container.network.rx_bytes_total` | `counter` | Running count of the number of network bytes received by the container | +| `tfe.container.network.rx_packets_total` | `counter` | Running count of the number of network packets received by the container | +| `tfe.container.network.tx_bytes_total` | `counter` | Running count of the number of network bytes transmitted by the container | +| `tfe.container.network.tx_packets_total` | `counter` | Running count of the number of network packets transmitted by the container | +| `tfe.container.disk.io_op_read_total` | `counter` | Running count of the number of read disk operations executed by the container | +| `tfe.container.disk.io_op_write_total` | `counter` | Running count of the number of write disk operations executed by the container | +| `tfe.container.disk.io_bytes_read_total` | `counter` | Running count of the number of disk bytes read by the container | +| `tfe.container.disk.io_bytes_write_total` | `counter` | Running count of the number of disk bytes written by the container | +| `tfe.container.process_count` | `gauge` | The number of processes active within the container | +| `tfe.container.process_limit` | `gauge` | The maximum number of processes that can be executed inside the container | + +The following metadata labels will be added to each container metric emitted: + +- `id`: The container ID +- `name`: The container name +- `image`: The container image + +-> **Note:** `tfe.container.*` metrics are not emitted on Kubernetes +installations. + +Worker container metrics include four additional labels: `run_type`, `run_id`, +`workspace_name`, and `organization_name`. You can use these labels to associate +a worker container with its type, run, workspace, and organization, +respectively. Metrics for long-running service containers will not include these +labels. + +In addition to the per-container metrics, the following global metrics are +exposed: + +| Exposed Metric | Metrics Type | Description | +| ----------------------- | ------------ | ----------------------------------------------------------------------------------------- | +| `tfe.run.count` | `gauge ` | Number of running containers being used for Terraform runs. | +| `tfe.run.limit` | `gauge` | Maximum number of runs as defined by the `TFE_CAPACITY_CONCURRENCY` environment variable. | +| `tfe.run.current.count` | `gauge` | Number of active Terraform runs labeled by organization, workspace, and status. | + +The name and ID for worker containers are unique for each run, and worker +container names take the form of a UUID. Be aware of this when planning for +Prometheus storage capacity requirements that relate to metric cardinality. +Environments that do not need to track resource consumption of individual build +containers or runs can use [Prometheus metric +relabelling](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs) +to remove the unique ID, name, and run type labels from container metrics. This +reduces cardinality within the dataset while still retaining the ability to +associate resource usage with a given workspace and organization. + +#### Grafana dashboard + +This [template Grafana dashboard](https://grafana.com/grafana/dashboards/15630) +demonstrates how you can use Grafana and Prometheus to visualize exported +Terraform Enterprise metrics. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/product-data.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/product-data.mdx new file mode 100644 index 0000000000..4983cd9acd --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/product-data.mdx @@ -0,0 +1,10 @@ +--- +page_title: Terraform Enterprise usage data reference +description: Learn about the product usage data Terraform Enterprise collects. +--- + +# Terraform Enterprise usage data reference + +This topic provides reference information about the product usage information Terraform Enterprise collects so that HashiCorp can improve service. Refer to [Enable automated product usage reports](/terraform/enterprise/deploy/manage/product-report). For information about how to configure Terraform Enterprise to automatically send product usage reports. + +@include "replicated-and-fdo/admin/license-example-usage-payload.mdx" \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/services.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/services.mdx new file mode 100644 index 0000000000..7f98e07499 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/services.mdx @@ -0,0 +1,72 @@ +--- +page_title: Terraform Enterprise services reference +description: Reference information about the services included with Terraform Enterprise. +--- + +# Terraform Enterprise services + +This topic provides reference information about the individual services in Terraform Enterprise. For information about troubleshooting service errors, refer to [Perform diagnostics](/terraform/enterprise/deploy/troubleshoot/perform-diagnostics). + +- `archivist` - Object storage API which simplifies the service architecture + and minimizes inner-network cross talk by colocating the logical storage and + front-end API handler pieces. + +- `atlas` - The Terraform Enterprise API. + +- `atlas-ui` - The Terraform Enterprise user interface. + +- `backup-restore` - A tool that provides both an API to backup and restore a + Terraform Enterprise backup snapshot and a command line tool to inspect a + backup snapshot. A backup snapshot is an encrypted binary file containing the + Archivist data, Vault transit keys, and PostgreSQL schema dumps for a given + Terraform Enterprise instance. + +- `licensing` - A library and service that provides enterprise license + functionality for Terraform. + +- `metrics` - A Terraform Enterprise component to aggregate metrics and expose + them over HTTP and HTTPS. + +- `nginx` - The NGINX reverse proxy which facilitates access to the Terraform + Enterprise services. + +- `outbound-http-proxy` - Security control used to filter user-controlled + network traffic (e.g. sentinel imports) and prevent them from accessing + internal services directly. + +- `postgres` - The PostgreSQL database holds relational data such as workspace + applies and where their state is stored in object storage. An internal + PostgreSQL service is started when the operational mode is `disk` on Docker runtime. PostgreSQL + server host config must be provided for application on cloud-managed Kubernetes, or for `external` and `active-active` operational mode on Docker runtime. + +- `redis` - An in-memory database, use for caching and `sidekiq` queue. An + internal Redis service is started when the operational mode is `disk` or + `external`. Redis server host config must be provided for `active-active` + mode for application on cloud-managed Kubernetes, or for `external` and `active-active` operational mode on Docker runtime. + +- `registry_api` - Terraform Private Module Registry API. + +- `sidekiq` - Background job scheduler system. + +- `slug-ingress` - Listens for VCS webhooks. Packages VCS repo data as a slug + and sends it to `archivist`. + +- `task-worker` - A service that manages asynchronous units of work in + Terraform Enterprise. + +- `terraform-registry-api` - The API to the Terraform Registry. + +- `terraform-registry-worker` - Processes VCS slugs and prepares modules to be + published on the Terraform private Module Registry. + +- `terraform-state-parser` - Reads Terraform state files and parses important + information out of them. Terraform state is consumed from a remote state URL, + and compiled data is sent in the payload of a callback to Atlas. + +- `tfe-health-check` - This tool is to help our customers and us know exactly + why Terraform Enterprise has gotten into an unhealthy state, checking the + health and connections to Postgres, Redis, Vault, storage, etc. + +- `vault` - HashiCorp Vault utilizes transit encryption for items such as + sensitive workspace variables. + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/startup-checks.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/startup-checks.mdx new file mode 100644 index 0000000000..a99d507bc9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/reference/startup-checks.mdx @@ -0,0 +1,109 @@ +--- +page_title: Startup checks reference +description: >- + Terraform Enterprise startup checks validate the Terraform Enterprise + configuration. Learn about the checks that run when you start Terraform Enterprise. +--- + +# Startup checks reference + +This topic contains reference information about Terraform Enterprise startup checks. The startup checks validate the configuration in order to prevent operators from starting Terraform Enterprise with invalid certificates and other issues that could prevent the application from running successfully or safely. + +Startup checks: + +- Run concurrently at startup +- Cannot be skipped +- Have a 1 minute timeout + +The results of the startup checks are logged alongside application logs. When +all of the startup checks pass, the application will continue to start up. + +``` +2023-06-30T17:54:58.628Z [INFO] terraform-enterprise: check passed: name=configuration duration="29.741µs" +2023-06-30T17:54:58.628Z [INFO] terraform-enterprise: check passed: name=database duration=10.053393ms +2023-06-30T17:54:58.628Z [INFO] terraform-enterprise: check passed: name=disk duration="169.438µs" +2023-06-30T17:54:58.628Z [INFO] terraform-enterprise: check passed: name=license duration=7.896534ms +2023-06-30T17:54:58.628Z [INFO] terraform-enterprise: check passed: name=redis duration="632.735µs" +2023-06-30T17:54:58.628Z [INFO] terraform-enterprise: check passed: name=tls duration="241.12µs" +2023-06-30T17:54:58.628Z [INFO] terraform-enterprise: check passed: name=upgrade duration=29.954ms" +``` + +If any of the startup checks fail, the application will log the checks that +failed and exit. Operators can check the logs for information on how they can +resolve the failing checks. + +``` +2023-06-30T18:14:45.792Z [INFO] terraform-enterprise: check passed: name=configuration duration="102.266µs" +2023-06-30T18:14:45.792Z [INFO] terraform-enterprise: check passed: name=database duration=11.925026ms +2023-06-30T18:14:45.792Z [INFO] terraform-enterprise: check passed: name=disk duration="360.432µs" +2023-06-30T18:14:45.792Z [ERROR] terraform-enterprise: check failed: name=license duration="423.448µs" err="failed parsing license: incorrectly formatted license" +2023-06-30T18:14:45.792Z [INFO] terraform-enterprise: check passed: name=redis duration="945.784µs" +2023-06-30T18:14:45.792Z [INFO] terraform-enterprise: check passed: name=tls duration="795.072µs" +2023-06-30T18:14:45.792Z [INFO] terraform-enterprise: check passed: name=upgrade duration=29.954ms" +2023-06-30T18:14:45.792Z [ERROR] terraform-enterprise: the following startup checks failed: checks=["license"] +2023-06-30T18:14:45.792Z [ERROR] terraform-enterprise: startup: error="startup checks failed" +``` + +## Types of checks + +Startup checks run the following validations to detect misses and gaps during the setup +of the installation. + +### Configuration Variables + +This check validates required configuration and acceptable values listed in the +[installation configuration reference](/terraform/enterprise/deploy/reference/configuration). + +### Database + +This check validates database access by querying for the supported version. When the database connection fails, it will retry using a linear backoff strategy. For external database configuration, the following must be set and are used for validation. +* `TFE_DATABASE_HOST` +* `TFE_DATABASE_NAME` +* `TFE_DATABASE_USER` +* `TFE_DATABASE_PASSWORD` + +The database validation can fail for the following reasons: + +* The database user set via `TFE_DATABASE_USER` has insufficient permissions to execute the query: `SHOW server_version;` +* The Postgres database version is a value other than `12`, `13`, `14` or `15`. + +### Filesystem access + +This validation only applies to application running `TFE_OPERATIONAL_MODE: disk` on Docker runtime. + +Validates the application has read / write privileges in the directory configured in `TFE_DISK_PATH`. This filesystem access validation can fail for the following reasons: + +* The application has no privilege to read / write files to the directory and its subdirectories configured in `TFE_DISK_PATH`. + +### License + +This check validates that the application has read privilege to the license and that it is a valid HashiCorp-provided license. License validation does not fail if the license is expired, but it can fail for the following reasons: + +- The license value was not provided via `TFE_LICENSE` or `TFE_LICENSE_PATH` is empty. + +### Redis + +This check validates the application's connectivity to Redis. When the connection fails, the check retries using a linear backoff strategy. For external Redis configurations, you must set the following variables: +* `TFE_REDIS_HOST` +* If `TFE_REDIS_USE_TLS` is set to `true` the application will use `rediss` instead of `redis` as the scheme. +* If `TFE_REDIS_USE_AUTH` is set to `true` the application will use the credentials provided by `TFE_REDIS_PASSWORD` and `TFE_REDIS_USER` (optional) for authentication. + +### TLS certificates + +This check validates that the `TFE_TLS_CA_BUNDLE_FILE` variable has been set and that it points to a valid PEM-encoded file. + +### Upgrade + +This check ensures that upgrades to Terraform Enterprise occur in a sequential manner and do not forego +[required Terraform Enterprise releases](/terraform/enterprise/releases). +The upgrade check fails and logs error messages if the following conditions apply: + +* A Terraform Enterprise instance is trying to upgrade to a version of the application that is not newer than the current version: +`"failed validating TFE version: vYYYYMM-P is not newer than existing version vYYYYMM-P"` + +* A Terraform Enterprise instance has skipped over required releases: +`"failed to meet upgrade requirements: missing required releases: vYYYYMM-P, vYYYYMM-P"` + +### Kubernetes + +This validation applies to `TFE_RUN_PIPELINE_KUBERNETES_POD_TEMPLATE`, if provided. It ensures that the template is a valid `corev1.PodTemplateSpec` and contains no more than one `corev1.Container`. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated-migration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated-migration.mdx new file mode 100644 index 0000000000..d70b9cc42f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated-migration.mdx @@ -0,0 +1,835 @@ +--- +page_title: Migrate from Replicated to another runtime +description: >- + Learn how to migrate your Terraform Enterprise installation from Replicated to another supported runtime environment. +--- + +# Migrate from Replicated to another runtime + +This topic describes how to migrate Terraform Enterprise instances from Replicated to another runtime environment. + +## Overview + +The target runtime must host instances on the same version of Terraform Enterprise as the instances hosted in Replicated. You cannot combine an application upgrade and migration. Upgrade your current installation of Terraform Enterprise to the latest version before proceeding with your migration. Use the same procedure to migrate from Replicated to all other supported runtimes: + +1. Back up your Terraform Enterprise data tier, which includes the PostgreSQL database and object storage. +1. Upgrade your existing Replicated installation to `v202309-1` or later. +1. Deploy the same version of Terraform Enterprise to your new runtime. +1. Migrate your data tier to your new installation. + +The migration paths are specific to the [operational mode](/terraform/enterprise/deploy/configuration/storage/configure-mode) of your existing Terraform Enterprise installation and the runtime environment you want to migrate to. + +- Docker: + + - Refer to the [Migrate Terraform Enterprise from Replicated to Docker Engine](https://www.hashicorp.com/resources/video-migrate-terraform-enterprise-from-replicated-to-docker-engine) video for a comprehensive walkthrough that describes how to migrate to a Docker runtime. + - [Migrating using mounted disk operational mode to Docker runtime](#mounted-disk-to-docker) + - [Migrating using external services operational mode to Docker runtime](#external-services-to-docker) + +- Kubernetes + + - [Migrating using mounted disk to Cloud-managed Kubernetes](#mounted-disk-to-cloud-managed-kubernetes) + - [Migrating using external services or Active/Active to Cloud-managed Kubernetes](#external-services-or-active-active-to-cloud-managed-kubernetes) + +- Podman + - The procedure for [migrating to Podman](#migrate-to-podman) is the same for `disk` and `external` operational modes. + +- Nomad + - [Migrating using mounted disk to Nomad](#mounted-disk-to-nomad) + - [Migrating using external services or Active/Active to Nomad](#external-services-or-active-active-to-nomad) + + + +## Prerequisites + +### Back up data tier + +1. We always recommend backing up your data tier before conducting maintenance or upgrade operations. The backup method will depend on your existing installation. + + - For mounted disk installations, refer to [Backup a Mounted Disk Deployment](/terraform/tutorials/recommended-patterns/pattern-backups#backup-a-mounted-disk-deployment) in the Terraform Enterprise backup tutorial for recommended patterns. + - For external services or active active installations, refer to [Object Store](/terraform/tutorials/recommended-patterns/pattern-backups#object-store) and [Database](/terraform/tutorials/recommended-patterns/pattern-backups#database) in the Terraform Enterprise backup tutorial for recommended patterns. + + In both cases, we recommend backing up the environment variables of the Terraform Enterprise Docker container so that you can refer to them when configuring your target runtime. + + ```shell-session + $ docker exec terraform-enterprise env > env.txt + ``` + +### Upgrade your existing Terraform Enterprise installation + +1. [Upgrade your Replicated-hosted Terraform Enterprise](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) installation to [v202309-1](/terraform/enterprise/releases/2023/v202309-1) or later. +1. Run the following commands to validate that the upgrade completed successfully: + 1. Validate the release version. + ```shell-session + $ replicatedctl app inspect + ``` + 1. Check that Replicated has started. + ```shell-session + $ replicatedctl app status + ``` + 1. Check that the docker containers are up. + ```shell-session + $ sudo docker ps + ``` + 1. Do a health check. + ```shell-session + $ tfe-admin health-check + ``` + 1. Do a `terraform plan` and a `terraform apply`. + +## Mounted disk to Docker + +Before proceeding with this migration guide, make sure you meet all the [prerequisites](#prerequisites) and that a Flexible +Deployment Options license file has been provided by your HashiCorp business partner. +Do not proceed with this guide if any of the prerequisites are not fulfilled. + +If at any point you need to revert your settings, see [the rollback steps](/terraform/enterprise/deploy/replicated-migration#mounted-disk-rollback-steps). + +### Migration steps + +#### Step 1: Backup your data tier + +We always recommend backing up your data tier before conducting any maintenance or migration. See the backup data guide under the [prerequisites](#prerequisites) section for a detailed +guide on how to move forward with the backup process. + +#### Step 2: Upgrade Terraform Enterprise + +Upgrade your Replicated-hosted Terraform Enterprise installation to [v202309-1](/terraform/enterprise/releases/2023/v202309-1) or later. Refer to [Upgrading](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) +for instructions. + +#### Step 3: Verify Docker Engine version + +Docker should already be installed for you because Replicated is installed on this host. You may still need to install Docker Compose if you have not already. +Refer to [Docker Engine Requirements](/terraform/enterprise/deploy/replicated/requirements/docker_engine) for more information. + +If you cannot upgrade Docker Engine or install in a supported Docker configuration then install and migrate Terraform Enterprise to a different runtime. + +#### Step 4: Generate Docker Compose configuration + +Docker Compose configurations generated on releases older than v202410-1 may contain formatting errors. Terraform Enterprise may format passwords or secrets that contain special characters incorrectly if your configuration contains double quotation marks instead of single quotation marks. + +To address this issue, you can manually replace double quotation marks with single quotation marks around secrets in your compose configuration. + +We fixed this issue in v202410-1. Refer to the [v202410-1 release notes](/terraform/enterprise/releases/2024/v202410-1) for additional information. + +To convert your existing configuration into a Docker Compose format on your current Terraform Enterprise installation (Replicated), follow these steps: +1. Create a `/etc/terraform-enterprise` directory. +1. Generate the Docker Compose configuration and save it to `/etc/terraform-enterprise/docker-compose.yml` using the following command: +```shell-session +sudo docker exec terraform-enterprise tfectl app config --format docker > /etc/terraform-enterprise/docker-compose.yml +``` +Your saved output should resemble the configuration file in [the example `disk` mode configuration](/terraform/enterprise/deploy/docker#example-disk-mode-configuration). Incorporate the saved output values into this configuration file to ensure correctness. + +Terraform Enterprise may generate a configuration that contains errors. Manually review the configuration to verify that it is complete and accurate. + +#### Step 5: Prepare the host and install + +To make migration smoother and faster, we recommend using the same host as your current Replicated instance. + +-> **Note**: If you want to use a separate host for your new docker-based Terraform Enterprise, we can provide alternative steps. [Reach out to support for assistance](/terraform/enterprise/deploy/troubleshoot/contact-support). + +1. Review the configuration file from the previous step. Update any values as needed before moving on to the next step. Pay special attention to placeholder values enclosed in `<>`, such as `image` and `TFE_LICENSE`, and replace them with your actual values. + + Alternatively, you can use the [mounted disk example](/terraform/enterprise/deploy/docker#example-disk-mode-configuration) as a starting point and adjust it to fit your environment. + + Note that the volumes `type` fields are set to `bind` for the `tfe` service. You can source many of your required values from the Replicated application configuration backup you created earlier. For a comprehensive list of configuration settings, refer to the [Configuration Reference](/terraform/enterprise/deploy/reference/configuration). + +1. Log in to the Terraform Enterprise container image registry. + + ```shell-session + $ cat | docker login --username terraform images.releases.hashicorp.com --password-stdin + ``` + +1. Pull the Terraform Enterprise image from the registry. + + ```shell-session + $ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + +1. Create a new `systemd` service for Terraform Enterprise by creating a `/etc/systemd/system/terraform-enterprise.service` file with [the contents on the Docker Installation guide](/terraform/enterprise/deploy/docker). Update this systemd unit file if any of the following are true: + + - The name or the path of the `docker-compose.yml` has changed. + - The path to the Docker binary and the command to invoke `docker compose` is different because Docker Engine 1.13.1 is installed. + +#### Step 6: Stop Replicated and migrate + +Next, you can stop Replicated and migrate your Terraform Enterprise installation to Docker. + +1. SSH into your Terraform Enterprise (Replicated) instance. +1. Stop Terraform Enterprise (Replicated). Ensure the application has fully stopped before proceeding. + ```shell-session + $ replicatedctl app stop + ``` +1. Back up your data. If you have already backed up your data proceed forward. If not, or if you want another backup for safe keeping, do the following. + - Retrieve your mounted disk path. + + ```shell-session + $ replicatedctl app-config export --template '{{ .disk_path.Value }}' | tr -d '\r' + ``` + + - We will refer to this path as the `${DISK_PATH}` going forward. Next, archive your mounted disk data. + + ```shell-session + $ tar -zcvf data.tar.gz -C ${DISK_PATH} aux postgres + ``` + - Copy your `data.tar.gz` archive to a safe place. + +1. Start (and enable on start up) the Docker Compose based Terraform Enterprise. + + ```shell-session + $ systemctl enable --now terraform-enterprise + ``` + +1. Check the status of your service with `systemctl status terraform-enterprise`, or use `docker ps` to find your container's name then run `docker logs [name]`. You can also run `curl https://[hostname]/_health_check` to check the health check endpoint. Terraform Enterprise should now be running using Docker Compose, so your Replicated services can be shut down and disabled. + +1. Shut down Replicated. + + ```shell-session + $ systemctl disable --now replicated replicated-ui replicated-operator + ``` + +1. Next, stop and remove the unnecessary Replicated containers. + ```shell-session + $ docker stop replicated-premkit + ``` + ```shell-session + $ docker stop replicated-statsd + ``` + ```shell-session + $ docker rm -f replicated replicated-ui replicated-operator replicated-premkit replicated-statsd retraced-api retraced-processor retraced-cron retraced-nsqd retraced-postgres + ``` + +-> **Note**: some of the `docker stop` commands may return “Container not found” errors because not every Replicated install has every container. + +#### Step 7: Validate migration success + +Finally, test that your new Terraform Enterprise installation works properly. If you have an existing suite of release acceptance tests, you can use those instead of doing the following steps. We recommend testing capabilities that you use in production, as you would for a Terraform Enterprise upgrade. For example: If you are using sentinel or run tasks in production, we recommend testing a run that includes these integrations in a lower environment before deploying to production. + +1. Execute a plan and apply it from the CLI, testing several subsystems. Ensuring that proxies are correctly configured, certificates are properly configured, and the instance can download Terraform binaries and execute runs. +1. Execute a plan and apply it from VCS, testing that webhooks are working and certificates are in place on both sides. +1. Publish a new module to the private module registry. +1. Execute a plan and apply it with a module or provider from the private registry to ensure the registry is functioning. +1. (_Optional_) Execute a plan and apply it with Sentinel and cost estimation, ensuring run tasks and cost estimation work. +1. (_Optional_) Execute a plan and apply it on a workspace that uses an agent pool, testing that external agents can connect and run jobs successfully. + +#### Mounted Disk rollback steps + +In the unlikely event you encounter issues and need to roll back, you can revert back to Terraform Enterprise (Replicated) using the following commands. + +1. Stop and disable Terraform Enterprise (Docker). + ```shell-session + $ systemctl disable --now terraform-enterprise + ``` +1. Start and enable Replicated. + ```shell-session + $ systemctl enable --now replicated replicated-ui replicated-operator + ``` +1. Start Terraform Enterprise (Replicated) + ```shell-session + $ replicatedctl app start + ``` + +## External services or Active Active to Docker + +Before proceeding with this migration guide, make sure you meet all the [prerequisites](#prerequisites) and that a Flexible +Deployment Options license file has been provided by your HashiCorp business partner. +Do not proceed with this guide if any of the prerequisites are not fulfilled. + +When Terraform Enterprise is operating in `active-active` mode, you can scale directly up to your target number of nodes after the migration is complete. You do not need to scale to one node before scaling to all nodes. + +If at any point you need to revert your settings, see [the rollback steps](/terraform/enterprise/deploy/replicated-migration#external-services-rollback-steps). + +### Migration steps + +#### Step 1: Backup your data tier + +We always recommend backing up your data tier before conducting any maintenance or migration. See the backup data guide under the [prerequisites](#prerequisites) section for a detailed +guide on how to move forward with the backup process. + +#### Step 2: Upgrade Terraform Enterprise + +Upgrade your Replicated-hosted Terraform Enterprise installation to [v202309-1](/terraform/enterprise/releases/2023/v202309-1) or later. Refer to [Upgrading](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) +for instructions. + +#### Step 3: Verify Docker engine version + +Docker should already be installed for you because Replicated is installed on this host. You may still need to install Docker Compose if you have not already. +See the [Docker Engine Requirements](/terraform/enterprise/deploy/replicated/requirements/docker_engine) for more information. + +If you cannot upgrade Docker Engine or install in a supported Docker configuration then install and migrate Terraform Enterprise to a different runtime. + +#### Step 4: Generate Docker Compose configuration + +Docker Compose configurations generated on releases older than v202410-1 may contain formatting errors. Terraform Enterprise may format passwords or secrets that contain special characters incorrectly if your configuration contains double quotation marks instead of single quotation marks. + +To address this issue, you can manually replace double quotation marks with single quotation marks around secrets in your compose configuration. + +We fixed this issue in v202410-1. Refer to the [v202410-1 release notes](/terraform/enterprise/releases/2024/v202410-1) for additional information. + +To convert your existing configuration into a Docker Compose format on your current Terraform Enterprise installation (Replicated), follow these steps: +1. Create a directory at `/etc/terraform-enterprise`. + +1. Generate the Docker Compose configuration and save it to `/etc/terraform-enterprise/docker-compose.yml` using the following command: + ```shell-session + sudo docker exec terraform-enterprise tfectl app config --format docker > /etc/terraform-enterprise/docker-compose.yml + ``` +Your saved output should resemble the configuration file in [our external services example](/terraform/enterprise/deploy/docker#example-external-mode-configuration). Incorporate the saved output values into this configuration file to ensure correctness. + +Terraform Enterprise may generate a configuration that contains errors. Manually review the configuration to verify that it is complete and accurate. + +#### Step 5: Prepare the host and install + +To make migration smoother and faster, we recommend using the same host(s) as your current Replicated instance. + +-> **Note**: If you want to use a separate host for your new docker-based Terraform Enterprise, we can provide alternative steps. [Reach out to support for assistance](/terraform/enterprise/deploy/troubleshoot/contact-support). + +1. Complete the instructions for creating and applying TLS certificates. Refer to [Create TLS certificates](/terraform/enterprise/deploy/prepare-host#create-tls-certificates) and [Set up installation folders and files](/terraform/enterprise/deploy/docker#set-up-installation-folders-and-files) for instructions. +1. Review the configuration file from previous step. Update any values as needed before moving on to the next step. Pay special attention to placeholder values enclosed in `<>`, such as `image` and `TFE_LICENSE`, and replace them with your actual values. + + Alternatively, you can use the [external services installation instructions for Docker deployments](/terraform/enterprise/deploy/docker#example-external-mode-configuration) or the [active-active installation instructions for Docker deployments](/terraform/enterprise/deploy/docker#example-active-active-mode-configuration) as a starting point and adjust it to fit your environment. + + Update, verify, and remove any unsuitable configuration variables that don't match the reality of your current Terraform Enterprise deployment. For a comprehensive list of available configuration settings, refer to the [Configuration Reference](/terraform/enterprise/deploy/reference/configuration). + + If you are operating Terraform in active-active mode then ensure that port 8201 is added to the exported docker ports to enable high availability requests from Vault. + + To quickly identify many of the required configuration values, inspect the existing Terraform Enterprise application using the `replicatedctl app-config export` command. + +1. Log into the registry and then use the `docker` command to pull the `terraform-enterprise` image version. + + ```shell-session + $ cat | docker login --username terraform images.releases.hashicorp.com --password-stdin + ``` + + When prompted for a password, use the contents of your HashiCorp license file as your password. + + ```shell-session + $ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + +1. Optionally create a new systemd service for Terraform Enterprise. Refer to [Manage the Docker service](/terraform/enterprise/deploy/docker#manage-the-docker-service) for instructions. + + -> **Note**: If you want to use a separate host for your new Docker-based Terraform Enterprise deployment, [contact HashiCorp support](/terraform/enterprise/deploy/troubleshoot/contact-support) for assistance. + +#### Step 6: Stop Replicated and migrate + +Next, you can stop Replicated and migrate your Terraform Enterprise installation to Docker. + +1. SSH into your Terraform Enterprise (Replicated) instance. +1. Stop Terraform Enterprise (Replicated). Ensure the application has fully stopped before proceeding. + ```shell-session + $ replicatedctl app stop + ``` + If you are operating Terraform in active-active mode then complete this step on all Terraform Enterprise hosts before continuing. +1. Start (and enable on start up) the Docker Compose based Terraform Enterprise. + ```shell-session + $ systemctl enable --now terraform-enterprise + ``` + If you are operating Terraform in active-active mode then complete this step on all Terraform Enterprise hosts before continuing. +1. Check the status of your service with `systemctl status terraform-enterprise`, or use `docker ps` to find your container's name then run `docker logs [name]`. You can also run `curl https://[hostname]/_health_check` to check the health check endpoint. Terraform Enterprise should now be running using Docker Compose, so your Replicated services can be shut down and disabled. + +1. Shut down Replicated. + + ```shell-session + $ systemctl disable --now replicated replicated-ui replicated-operator + ``` + +1. Next, stop and remove the unnecessary Replicated containers. + ```shell-session + $ docker stop replicated-premkit + ``` + ```shell-session + $ docker stop replicated-statsd + ``` + ```shell-session + $ docker rm -f replicated replicated-ui replicated-operator replicated-premkit replicated-statsd retraced-api retraced-processor retraced-cron retraced-nsqd retraced-postgres + ``` + +-> **Note**: Some of the `docker stop` commands may return “Container not found” errors because not every Replicated install has every container. + +#### Step 7: Validate migration success + +Finally, test that your new Terraform Enterprise installation works properly. If you have an existing suite of release acceptance tests, execute those instead of doing the following steps. We recommend testing capabilities that you use in production, as you would for a Terraform Enterprise upgrade. For example: If you are using sentinel or run tasks in production, we recommend testing a run that includes these integrations in a lower environment before deploying to production. + +1. Execute a plan and apply it from the CLI, testing several subsystems. Ensuring that proxies are correctly configured, certificates are properly configured, and the instance can download Terraform binaries and execute runs. +1. Execute a plan and apply it from VCS, testing that webhooks are working and certificates are in place on both sides. +1. Publish a new module to the private module registry. +1. Execute a plan and apply it with a module or provider from the private registry to ensure the registry is functioning. +1. (_Optional_) Execute a plan and apply it with Sentinel and cost estimation, ensuring run tasks and cost estimation work. +1. (_Optional_) Execute a plan and apply it on a workspace that uses an agent pool, testing that external agents can connect and run jobs successfully. + +#### External Services or Active Active rollback steps + +In the unlikely event you encounter issues and need to roll back, you can revert back to Terraform Enterprise (Replicated) using the following commands. + +1. Stop and disable Terraform Enterprise (Docker). + ```shell-session + $ systemctl disable --now terraform-enterprise + ``` + If you are operating Terraform in active-active mode then complete this step on all Terraform Enterprise hosts before continuing. +1. Start and enable Replicated. + ```shell-session + $ systemctl enable --now replicated replicated-ui replicated-operator + ``` +1. Start Terraform Enterprise (Replicated) + ```shell-session + $ replicatedctl app start + ``` + If you are operating Terraform in active-active mode then complete this step on all Terraform Enterprise hosts before continuing. + +## Mounted disk to Cloud-managed Kubernetes + +You must provide an external PostgreSQL database server, external object storage, and external Redis storage. Refer to the [prerequisites for deploying to Kubernetes](/terraform/enterprise/deploy/kubernetes#prerequisites) for additional information. + +If you currently use the [mounted disk operational mode](/terraform/enterprise/operational-modes#operational-modes) for Terraform Enterprise on Replicated, you do not meet the above requirements. +You must first [migrate to external services mode](/terraform/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration), and then follow the external services to Kubernetes migration guide as well as deploy an external Redis server. +At a high level, this process involves: + +1. [Backing up your data](/terraform/tutorials/recommended-patterns/pattern-backups#backup-a-mounted-disk-deployment). +1. [Restoring your data to external services](/terraform/tutorials/recommended-patterns/pattern-recovery). +1. Testing that the external services migration succeeded. +1. Deploying external redis. +1. Follow the guide for [External Services to Kubernetes migration](/terraform/enterprise/deploy/replicated/replicated-migration#external-services-or-active-active-to-cloud-managed-kubernetes). + +Contact your HashiCorp account representative or HashiCorp support if you have additional questions. + +## External services or Active/Active to Cloud-managed Kubernetes + +Redis is a _required service_ for running Terraform Enterprise in Kubernetes. If your deployment is in operating in [`external` mode](/terraform/enterprise/deploy/reference/configuration#external), you must deploy an external Redis server. + +If you are currently operating Terraform Enterprise in `active-active` mode, then you have all required service dependencies for migrating to Kubernetes. Refer to the [prerequisites for deploying to Kubernetes](/terraform/enterprise/deploy/kubernetes#prerequisites) for additional information. + +Before proceeding with this migration guide, make sure you meet all the [prerequisites](#prerequisites) and that a Flexible +Deployment Options license file has been provided by your HashiCorp business partner. +Do not proceed with this guide if any of the prerequisites are not fulfilled. + +When Terraform Enterprise is operating in `active-active` mode, you can scale directly up to your target number of nodes after the migration is complete. You do not need to scale to one node before scaling to all nodes. + +If at any point you need to revert your settings, see [the rollback steps](/terraform/enterprise/deploy/replicated-migration#kubernetes-rollback-steps). + +### Migration steps + +#### Step 1: Backup your data tier + +We always recommend backing up your data tier before conducting any maintenance or migration. See the backup data guide under the [prerequisites](#prerequisites) section for a detailed +guide on how to move forward with the backup process. + +#### Step 2: Upgrade Terraform Enterprise + +Upgrade your Replicated-hosted Terraform Enterprise installation to [v202309-1](/terraform/enterprise/releases/2023/v202309-1) or later. Refer to [Upgrading](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) +for instructions. + +#### Step 1: Prepare the custom Helm Values file for Terraform Enterprise + +1. On Terraform Enterprise (Replicated), view existing configuration: + + ```shell-session + $ replicatedctl app-config export + ``` + +1. Create a custom [Helm Values file](https://helm.sh/docs/chart_template_guide/values_files/) e.g `overrides.yaml` to override the [default values](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/values.yaml) in the [Terraform Enterprise Helm chart](https://github.com/hashicorp/terraform-enterprise-helm/tree/main). + +1. On the `env.secrets` and `env.variables` sections of the [overrides values file](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/values.yaml), use the external services credentials from the Replicated installation for the Kubernetes installation. Specifically the following: + 1. The `TFE_OBJECT_STORAGE_TYPE` and `TFE_OBJECT_STORAGE_*` variables should specify the object storage type and the container or bucket credentials from your Replicated installation. + 1. The `TFE_DATABASE_*` variables should specify database credentials from the Replicated installation. + 1. The `TFE_REDIS_*` values on the Helm chart should specify the same credentials from the external Redis in your Replicated installation. + 1. If there is an external vault, the `TFE_VAULT_*` values on the Helm chart should specify the same credentials from the external Vault in your Replicated installation. + 1. The `TFE_ENCRYPTION_PASSWORD` value should match the Replicated installation value. You can get this from your Replicated instance via SSH by running the following command: + ```shell-session + $ replicatedctl app-config export --template '{{ .enc_password.Value }}' + ``` + Refer to the [Replicated to flexible deployments configuration mapping](/terraform/enterprise/deploy/reference/configuration#replicated-to-flexible-deployments-configuration-mapping) for more information on how the Replicated configuration maps to the variables and secrets on Terraform Enterprise Helm chart. + + Refer to the [example Kubernetes configuration](/terraform/enterprise/deploy/kubernetes#examples) for additional reference information about cloud-specific override values for the Helm deployment. + +#### Step 2: Migrate to Kubernetes + +1. Stop your Replicated installation by executing the following command: + + ```shell-session + $ replicatedctl app stop + ``` + +1. Wait for the application to stop: + + ```shell-session + $ replicatedctl app status + ``` + +1. [Install Terraform Enterprise on Kubernetes using Helm](/terraform/enterprise/deploy/kubernetes). + +#### Step 3: Validate migration success + +Finally, test that your new Terraform Enterprise installation works properly. If you have an existing suite of release acceptance tests, you can use those instead of doing the following steps. We recommend testing capabilities that you use in production, as you would for a Terraform Enterprise upgrade. For example: If you are using sentinel or run tasks in production, we recommend testing a run that includes these integrations in a lower environment before deploying to production. You should +be able to log in to your new Terraform Enterprise installation with the credentials previously used for your Replicated installation. + +1. Execute a plan and apply it from the CLI, testing several subsystems. Ensuring that proxies are correctly configured, certificates are properly configured, and the instance can download Terraform binaries and execute runs. +1. Execute a plan and apply it from VCS, testing that webhooks are working and certificates are in place on both sides. +1. Publish a new module to the private module registry. +1. Execute a plan and apply it with a module or provider from the private registry to ensure the registry is functioning. +1. (_Optional_) Execute a plan and apply it with Sentinel and cost estimation, ensuring run tasks and cost estimation work. +1. (_Optional_) Execute a plan and apply it on a workspace that uses an agent pool, testing that external agents can connect and run jobs successfully. + +#### Kubernetes rollback steps + +In the unlikely event you encounter issues that cannot be worked around, you can rollback to Terraform Enterprise (Replicated). + +1. If it is possible to `exec` into the pods, run the `node drain` command to stop Terraform Enterprise from executing further instructions. + + ```shell-session + $ tfectl node drain --all + ``` + +1. Uninstall the deployment. + + ```shell-session + $ helm uninstall terraform-enterprise + ``` + +1. Restart Terraform Enterprise on Replicated using the same external services. + ```shell-session + $ replicatedctl app start + ``` + +## Migrate to Podman + +Before proceeding with this migration guide, make sure you meet all the [prerequisites](#prerequisites) and that a Flexible +Deployment Options license file has been provided by your HashiCorp business partner. +Do not proceed with this guide if any of the prerequisites are not fulfilled. + +Complete the following steps to migrate from Replicated to Podman. + +The minimum Terraform Enterprise version necessary for Podman is [v202404-1](/terraform/enterprise/releases/2024/v202404-1). + +When Terraform Enterprise is operating in `active-active` mode, you can scale directly up to your target number of nodes after the migration is complete. You do not need to scale to one node before scaling to all nodes. + +#### Step 1: Prepare the host + +We recommend deploying Terraform Enterprise to the same host as your current Replicated instance. + +[Contact HashiCorp support](/terraform/enterprise/deploy/troubleshoot/contact-support) for assistance migrating your Terraform Enterprise installation to a separate host. + +1. We recommend reusing your Replicated certificate to minimize the upgrade's effect on your other stack components. + + Create a directory with the following: + + - TLS certificate (`cert.pem`) + - TLS private key (`key.pem`) + - CA certificates bundle (`bundle.pem`) + + If you do not have a CA certificates bundle, place your TLS certificate (`cert.pem`) inside `bundle.pem` instead. + Add your certificates to a folder on your host. + + If you cannot access your certificate, key, or bundle file, you can retrieve them from the Replicated Terraform Enterprise container. Run the following command to list the certificate paths in the container: + + ```sh + docker exec terraform-enterprise tfectl app config --unredacted | jq '{cert: .tls.cert_file, key: .tls.key_file, bundle: .tls.ca_bundle_file}' + ``` + + Depending on your setup, the file paths may differ from the following example output: + + ```sh + { + "cert": "/etc/ssl/private/terraform-enterprise/cert.pem", + "key": "/etc/ssl/private/terraform-enterprise/key.pem", + "bundle": "/etc/ssl/private/terraform-enterprise/bundle.pem" + } + ``` + + You can then copy the files from the container into the host. + + ```sh + docker cp terraform-enterprise:/etc/ssl/private/terraform-enterprise/cert.pem /cert.pem + docker cp terraform-enterprise:/etc/ssl/private/terraform-enterprise/key.pem /key.pem + docker cp terraform-enterprise:/etc/ssl/private/terraform-enterprise/bundle.pem /bundle.pem + ``` + +1. Next, backup your Replicated configuration. + Your Replicated configuration contains necessary information, such as the `` as `enc_password` and the `` as `disk_path`. + + ``` + replicatedctl app-config export > replicated-app-config.backup.json + ``` + +1. Create a yaml file based on the template for your current operational mode: + - [Mounted Disk operational mode Kubernetes YAML example](/terraform/enterprise/deploy/podman#example-disk-mode-configuration). + - [External operational mode Kubernetes YAML example](/terraform/enterprise/deploy/podman#example-external-mode-configuration). + - [Active/Active operational mode Kubernetes YAML example](/terraform/enterprise/deploy/podman#example-active-active-mode-configuration). + + Replace the values enclosed in `<>` with your installation's values. For example, set `TFE_HOSTNAME` to the DNS hostname you use to access Terraform Enterprise. + +#### Step 2: Stop Terraform Enterprise and remove Replicated + +Replicated runs using `docker`, while Podman uses `podman-docker`. Installing Podman removes docker, which is why we recommend backing up your data before stopping your Terraform Enterprise instance. Ensure you have [backed up your data](#step-1-backup-your-data-tier-3) and [Replicated configuration](#step-3-prepare-the-host) before proceeding. + +1. Stop Terraform Enterprise (Replicated). Ensure the application has fully stopped before proceeding. + + ```shell-session + $ replicatedctl app stop + ``` + +1. Shut down Replicated. + + ```shell-session + $ systemctl disable --now replicated replicated-ui replicated-operator + ``` + +1. Next, stop and clean up your unnecessary Replicated containers. + ```shell-session + $ docker stop replicated-premkit + ``` + ```shell-session + $ docker stop replicated-statsd + ``` + ```shell-session + $ docker rm -f replicated replicated-ui replicated-operator replicated-premkit replicated-statsd retraced-api retraced-processor retraced-cron retraced-nsqd retraced-postgres + ``` + +#### Step 3: Install Podman + +Verify that you have met the [prerequisites for deploying to Podman](/terraform/enterprise/deploy/podman#prerequisites) before installing Terraform Enterprise on Podman. +Follow the [Podman installation guide](/terraform/enterprise/deploy/podman). + +#### Step 4: Download and install image + +1. Log into the Terraform Enterprise container image registry using `terraform` + as the username and your HashiCorp Terraform Enterprise license as the password: + + ```shell-session + $ echo "" | podman login --username terraform images.releases.hashicorp.com --password-stdin + ``` + +1. Pull the Terraform Enterprise image from the registry. + + ```shell-session + $ podman pull images.releases.hashicorp.com/hashicorp/terraform-enterprise: + ``` + +#### Step 5: Start a Terraform pod + +1. Create a Terraform Enterprise pod by running the following command: + + ```shell-session + $ podman kube play + ``` + +1. In a separate terminal session, you can monitor the logs by running the following command: + + ```shell-session + $ podman logs -f + ``` + +1. Monitor the health of the application until it starts reporting healthy with the following command: + + ```shell-session + $ podman exec tfe-health-check-status + ``` + +#### Step 6: Validate migration success + +Complete the following steps to verify that your new Terraform Enterprise installation works as expected. Alternatively, you can execute your existing suite of release acceptance tests. We recommend testing capabilities that you use in production, as you would for a Terraform Enterprise upgrade. For example: If you are using sentinel or run tasks in production, we recommend testing a run that includes these integrations in a lower environment before deploying to production. + +1. Execute a plan and apply it from the CLI to test several subsystems. This step ensures that proxies are correctly configured, certificates are properly configured, and that the instance can download Terraform binaries and execute runs. +1. Execute a plan and apply it from version control to test that webhooks are working and certificates are in place on both sides. +1. Publish a new module to the private module registry. +1. Execute a plan and apply it with a module or provider from the private registry to ensure the registry is functioning. +1. (_Optional_) Execute a plan and apply it with Sentinel and cost estimation policies enabled. This step ensures that run tasks and cost estimation function as expected. +1. (_Optional_) Execute a plan and apply it on a workspace that uses an agent pool to verify that external agents can connect and run jobs successfully. + +#### Mounted Disk rollback steps + +Complete the following steps to revert to a Replicated deployment. + +1. Stop Terraform Enterprise on Podman. + + ```shell-session + $ podman kube down + ``` + +2. Remove Podman. + + ```shell-session + $ dnf module remove -y container-tools + ``` + + ```shell-session + $ dnf remove -y podman-docker + ``` + +3. Install Terraform Enterprise on Replicated. + + If available, you can reuse the instance initialization script to reinstall Terraform Enterprise on Replicated. Otherwise, refer to the [Replicated installation guide](/terraform/enterprise/deploy/replicated/install/interactive/installer#installation). + +## Mounted disk to Nomad + +You must provide an external PostgreSQL database server, external object storage, and external Redis storage. Refer to the [prerequisites for deploying to Nomad](/terraform/enterprise/deploy/nomad#prerequisites) for additional information. + +You must complete additional steps to migrate a Terraform Enterprise deployment on Replicated in [`disk` mode](/terraform/enterprise/deploy/storage/configure-mode): + +1. [Migrate your Replicated deployment to `external` mode](/terraform/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration) +1. Verify that the migration succeeded. +1. Deploy an external Redis server. + +You can then complete the steps for migrating to Nomad in `external` mode: + +1. Back up your data. Refer to the [Backup a Mounted Disk Deployment](/terraform/tutorials/recommended-patterns/pattern-backups#backup-a-mounted-disk-deployment) for instructions. +1. Restore your data to external services. Refer to the [Terraform Enterprise recovery and restore - recommended pattern](/terraform/tutorials/recommended-patterns/pattern-recovery) tutorial for instructions. +1. Verify that the external services migration succeeded. +1. Complete the steps for migrating to Nomad in `external` mode. Refer to [External Services to Nomad migration](/terraform/enterprise/deploy/replicated-migration#external-services-or-active-active-to-nomad) for instructions. + +Contact your HashiCorp account representative or HashiCorp support if you have additional questions. + +## External services or Active/Active to Nomad + +Redis is required to run Terraform Enterprise in Nomad. If you are migrating a Replicated deployment in [`external` operational mode](/terraform/enterprise/operational-modes#operational-modes), you need to deploy an external Redis server. + +If you are migrating a Replicated deployment in `active-active` operational mode, you should already have all the required service dependencies. Refer to the [prerequisites for deploying to Nomad](/terraform/enterprise/deploy/nomad#prerequisites) for additional information. + +Before proceeding, verify that you meet the [prerequisites](#prerequisites) and that you have a Terraform Enterprise license file. Do not continue if any of the prerequisites are not fulfilled. + +If you need to revert at any point, refer to [Nomad rollback steps](/terraform/enterprise/deploy/replicated-migration#nomad-rollback-steps) for instructions. + +### Migration steps +Complete the following steps to perform the migration. +#### Step 1: Backup your data tier + +Back up your data tier before conducting any maintenance or migration. Refer to [Back up data tier](#back-up-data-tier) for instructions. + +#### Step 2: Upgrade to a compatible version of Terraform Enterprise + +The existing version of Terraform Enterprise must be able to run on non-Replicated runtimes. Refer to [Upgrade existing Terraform Enterprise installation to a compatible version](#upgrade-existing-terraform-enterprise-installation-to-a-flexible-deployment-options-compatible-version) for upgrade instructions. +#### Step 3: Prepare the Nomad job file for Terraform Enterprise + +1. Run the following command to view existing configuration: + + ```shell-session + $ replicatedctl app-config export + ``` + +1. Create a Nomad job file for Terraform Enterprise. Refer to [Configure Terraform Enterprise Nomad job specification](/terraform/enterprise/deploy/nomad#configure-terraform-enterprise-nomad-job-specification) for additional information. + +1. In the Terraform Enterprise Nomad job specification, specify the following values: + 1. The `TFE_OBJECT_STORAGE_TYPE` and `TFE_OBJECT_STORAGE_*` variables should specify the object storage type and the container or bucket credentials from your Replicated installation. + 1. The `TFE_DATABASE_*` variables should specify database credentials from the Replicated installation. + 1. The `TFE_REDIS_*` values on the Helm chart should specify the same credentials from the external Redis in your Replicated installation. + 1. If Terraform Enterprise is connected to an external Vault server, the `TFE_VAULT_*` values on the Helm chart should specify the same credentials from the external Vault in your Replicated installation. + 1. The `TFE_ENCRYPTION_PASSWORD` value should match the Replicated installation value. You can get this from your Replicated instance by connecting to the instance over SSH and running the following command: + ```shell-session + $ replicatedctl app-config export --template '{{ .enc_password.Value }}' + ``` + Refer to the [Replicated to flexible deployments configuration mapping](/terraform/enterprise/deploy/reference/configuration#replicated-to-flexible-deployments-configuration-mapping) for details about the configurations. + +#### Step 4: Migrate to Nomad + +When Terraform Enterprise is operating in `active-active` mode, you can scale directly up to your target number of nodes after the migration is complete. You do not need to scale to one node before scaling to all nodes. + +1. Stop your Replicated installation by executing the following command: + + ```shell-session + $ replicatedctl app stop + ``` + +1. Wait for the application to stop: + + ```shell-session + $ replicatedctl app status + ``` + +1. Install Terraform Enterprise on Nomad. Refer to [Deply Terraform Enterprise to Nomad](/terraform/enterprise/deploy/nomad) for instructions. + +#### Step 5: Validate migration success + +Verify that your new Terraform Enterprise installation works properly. If you have an existing suite of release acceptance tests, you can use them instead of completing the following steps. We recommend testing capabilities that you use in production, as you would for a Terraform Enterprise upgrade. For example: If you are using sentinel or run tasks in production, we recommend testing a run that includes these integrations in a lower environment before deploying to production. You should +be able to log in to your new Terraform Enterprise installation with the credentials previously used for your Replicated installation. + +1. Execute a plan and apply it from the CLI, testing several subsystems. Ensuring that proxies are correctly configured, certificates are properly configured, and the instance can download Terraform binaries and execute runs. +1. Execute a plan and apply it from VCS, testing that webhooks are working and certificates are in place on both sides. +1. Publish a new module to the private module registry. +1. Execute a plan and apply it with a module or provider from the private registry to ensure the registry is functioning. +1. (_Optional_) Execute a plan and apply it with Sentinel and cost estimation, ensuring run tasks and cost estimation work. +1. (_Optional_) Execute a plan and apply it on a workspace that uses an agent pool, testing that external agents can connect and run jobs successfully. + +#### Nomad rollback steps + +Complete the following steps if an unresolvable issue emerges: + +1. If you are able to connect to a job allocation using the [`nomad alloc exec`](/nomad/docs/commands/alloc/exec) command, run the `node drain` command to stop Terraform Enterprise from executing further instructions. + + ```shell-session + $ tfectl node drain --all + ``` + +1. Stop Terraform Enterprise job and purge it. + + ```shell-session + $ nomad job stop -purge -namespace=$namespace + ``` + +1. Optionally, cleanup Nomad variables, ACLs, and namespaces. + + ```shell-session + $ nomad var purge -namespace=$namespace + ``` + + ```shell-session + $ nomad acl policy delete -namespace=$namespace + ``` + + ```shell-session + $ nomad namespace delete -force $namespace + ``` + +1. Restart Terraform Enterprise on Replicated using the same external services. + ```shell-session + $ replicatedctl app start + ``` + +## Troubleshooting + +Refer to the following documentation to ensure you have uninterrupted visibility into the health of the application: + +- [Startup checks reference](/terraform/enterprise/deploy/reference/startup-checks) + +- [Monitor Terraform Enterprise](/terraform/enterprise/deploy/manage/monitor) + +- [Metrics reference](/terraform/enterprise/deploy/reference/metrics) + +### Common Issues + +Below are a list of common migration issues and symptoms of those issues. + +#### Self signed certificates CA not in CA bundle + +##### Symptoms: + +- Plans fail +- Errors in `/var/log/terraform-enterprise/task-worker.log` and `/var/log/terraform-enterprise/atlas.log`, particularly when making calls to Archivist, where the certificate is from an unknown issuer. + +##### Fix: + +- Bring the additional certificates from the full chain certificate into the CA bundle +- Note that this action is partially automated when deploying to Replicated. For other runtimes, you may need to manually concatenate the certificates from the full chain certificate into the CA bundle for the instance to talk to itself. + +#### Required CA not in CA bundle + +##### Symptom: + +- Setting up VCS fails with unknown certificate issuer error + +##### Fix: + +- Include the CA in the CA Bundle + +#### Internal calls to instance or AWS Metadata Endpoint unnecessarily proxied + +##### Symptom: + +- Plans May fail, Logs may fail to load (but not always) +- The proxy directs traffic unexpectedly + +##### Fix: + +- When deployed to Replicated, Terraform builds much of the default `no_proxy` or `NO_PROXY` address list, but you are responsible for managing the list when deploying to the other supported runtimes. In addition to manually adding the entries from your Replicated `Additional No Proxy List` configuration, add the following entries to the `no_proxy` or `NO_PROXY` address list: + - `localhost` + - `127.0.0.1` + - `169.254.169.254` + - FQDN of instance + - Rest of `no_proxy` list diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/index.mdx new file mode 100644 index 0000000000..3596680a26 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/index.mdx @@ -0,0 +1,18 @@ +--- +page_title: Administration for Replicated deployments overview +description: >- + Learn about administrating Terraform Enterprise deployments on the legacy Replicated platform. +--- + +# Administration for Replicated deployments overview + +This topic contains overview information administrating the Terraform Enterprise host and infrastructure when deployed to the legacy Replicated runtime. For information about administration for non-Replicated runtimes, including Docker, Kubernetes, Nomad, OpenShift, and Podman, refer to [Manage Terraform Enterprise deployment overview](/terraform/enterprise/deploy/manage). + +## Workflows + +Installing and managing a Terraform Enterprise involves administering both the [application](/terraform/enterprise/application-administration) itself and the infrastructure behind that application. + +You can perform the following actions: + +- [Manage your HashiCorp license](/terraform/enterprise/deploy/replicated/administration/license) +- [Manage your infrastructure](/terraform/enterprise/deploy/replicated/administration/infrastructure) \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/admin-cli.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/admin-cli.mdx new file mode 100644 index 0000000000..46aca748dd --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/admin-cli.mdx @@ -0,0 +1,169 @@ +--- +page_title: Admin CLI Commands - Infrastructure Administration - Terraform Enterprise +description: >- + Use the admin CLI to configure Terraform Enterprise when in active/active mode. Learn how to change the configuration, stop the application safely, upgrade TFE, and patch Terraform Enterprise instances using the CLI. +--- + +# Terraform Enterprise Admin CLI Commands + +The [Active/Active](/terraform/enterprise/deploy/replicated/install/automated/active-active) operational mode disables the Replicated Admin Console. Instead, it provides admin CLI commands to change the configuration, stop the application safely, and produce support bundles. You must use SSH to log in to a node in the Active/Active cluster to run these commands. + +Admin CLI commands are available on installations using the Standalone operational mode. + +### Commands + +Note that `tfe-admin` is an alias for `replicated admin`, and can be used interchangeably. + +#### support-bundle + +```bash +tfe-admin support-bundle +``` + +This command generates a support bundle for all nodes. + +The support bundle will be created in `/var/lib/replicated/support-bundles`. + +For External Services and Active/Active installations, the support bundles will be uploaded to the same object store bucket that is used to store Terraform state files. The support bundles for a specific run of the admin command will all be uploaded to a directory with the same JobID, which is a timestamp in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) format. If you are sending a support bundle to HashiCorp Support, package and send all associated bundles to ensure that we have all the necessary information. + +Example upload structure + +```bash +support-bundles +└── 2020-11-10T02:03:05Z + ├── 10.0.0.5 + │ └── replicated-support702524260.tar.gz + └── 10.0.0.6 + └── replicated-support577188727.tar.gz +``` + +#### node-drain + +```bash +tfe-admin node-drain +``` + +This command will quiesce the current node and remove it from service. It will allow current work to complete and safely stop the node from picking up any new jobs from the Redis queue, allowing the application to be safely stopped. Currently, it only affects `localhost` (it does not support running on one node to drain other nodes). + +-> **Note:** There is no reverse drain command - a restart is needed to restore the node. + +#### app-config + +```bash +replicatedctl app-config set --value +``` + +This command allows you to use the CLI to make real-time application changes, such as `capacity_concurrency`. You must provide both an allowable `` (setting name) and `` (new setting value). Run `replicatedctl app-config export` for a complete list of the current `app-config` settings. + +For the configuration changes to take effect, you must restart the Terraform Enterprise application **on each node instance**. To restart Terraform Enterprise: + +1. Run `replicatedctl app stop` to stop the application. +1. Run `replicatedctl app status` to confirm the application is stopped. +1. Run `replicatedctl app start` to start the application. + +-> **Note:** You should ensure that any ad hoc changes made in this fashion are captured in the standard node build configuration, as the next time you build/rebuild a node only the configuration stored for that purpose will be in effect and ad hoc changes could be lost. + +-> **Hint:** Adding a function to your Linux start-up like an alias can give you a short cut to the admin `app-config` command only requiring a single command and parameters, such as: + +```bash +# shortcut: tfe-app-config +tfe-app-config () +{ + replicatedctl app-config set "$1" --value "$2" +} +``` + +#### list-nodes + +```bash +tfe-admin list-nodes +``` + +This command lists the IP addresses of all active nodes in the installation. Nodes send a heartbeat every 5 seconds to signal that they are active. If Terraform Enterprise does not receive a heartbeat from a node within 30 seconds, it considers the node inactive and removes the node from the list. + +#### rotate-encryption-password + +```bash +tfe-admin rotate-encryption-password CURRENT_PASSWORD NEW_PASSWORD +``` + +This command rotates the [encryption password](/terraform/enterprise/deploy/replicated/install/automated/encryption-password) in use by Terraform Enterprise. + +To prevent sensitive information from being stored in the shell history, temporarily write the current and new encryption passwords to files and read them upon execution, deleting the temporary files when finished: + +```bash +tfe-admin rotate-encryption-password "$(cat current_password.txt)" "$(cat new_password.txt)" +``` + +A successful encryption password rotation will show the following output: + +```bash +Encryption password successfully rotated! + +Updating the `enc_password` application configuration on 2 node(s) to reflect the new encryption password. + +You must update any installation or automation processes to reflect the new encryption password! +``` + +An unsuccessful encryption password rotation will show an error: + +```bash +Error rotating encryption password: +Error: +exit status 1 +Output: +Encryption password not rotated! +Error reading previous Vault configuration: failed decrypting unseal key: could not decrypt ciphertext: chacha20poly1305: message authentication failed +``` + +#### license-info + +```bash +tfe-admin license-info +``` + +This command lists the license information and workspace count for the Terraform Enterprise installation on which it is run. + +## Other Supporting Commands + +There are additional commands available for checking status and troubleshooting directly on nodes. You can use them to confirm successful installation or to check on the status of a running node as part of troubleshooting activities. Also, there are additional command aliases available that allow you to run more abbreviated versions of commands like just `support-bundle`. Run an `alias` command with no parameters to see the list of available command aliases. + +### Commands + +#### health-check + +```bash +tfe-admin health-check +(alias health-check) +``` + +This command tests and reports on the status of the major Terraform Enterprise services. Each will be listed as PASS or FAIL. If any are marked as FAIL, your Terraform Enterprise implementation is NOT healthy and additional action must be taken. + +#### replicated status + +```bash +replicatedctl system status +``` + +Displays status info on the Replicated sub-system. Key values to note are that status values return as "ready". This reports on the status of the system on the node instance that it is run on. + +#### Terraform Enterprise application status + +```bash +replicatedctl app status +``` + +Displays status info on the Terraform Enterprise application. Key values to note are that `State` and `DesiredState` are both "started" and `IsTransitioning` is false. This reports on the status of the application on the node instance that it is run on. + +## Upgrading Terraform Enterprise or Patching Terraform Enterprise Node Instances + +The mechanism used to upgrade the Terraform Enterprise node instances is to fully repave the instances (destroy and rebuild entirely). +This is another reason why using automation to build the instances is important. Currently, the safest way to perform and upgrade is to shut down all node instances, rebuild one node to validate a successful upgrade, and then scale to additional nodes (currently max 5). + +These are the steps required to repave the node instances: + +- Run the `node-drain` command as described previously on each node to complete active work and stop new work from being processed. +- Update the instance build configuration such as setting a new `ReleaseSequence` to upgrade versions and/or make any other alterations such as patching the base image used for building the instances. +- Follow the instructions in [Terraform Enterprise Active/Active](/terraform/enterprise/deploy/replicated/install/automated/active-active#scale-down-to-zero-nodes) to scale down to zero nodes and proceed through scaling up to one node, validating success, and then scaling additional nodes. + +If planned and orchestrated efficiently, the total downtime for the repaving will be the amount of time it has taken to build one node as processing will resume as soon as the first node is functional. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/automated-recovery.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/automated-recovery.mdx new file mode 100644 index 0000000000..923be6bef1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/automated-recovery.mdx @@ -0,0 +1,251 @@ +--- +page_title: Automated Recovery - Infrastructure Administration - Terraform Enterprise +description: >- + Use automated recovery to provice a short Mean-Time-To-Recovery (MTTR) in the event of an outage. Learn how to configure and restore snapshots. +--- + +# Terraform Enterprise Automated Recovery + +This guide explains how to configure automated recovery for a Terraform +Enterprise installation. The goal is to provide a short Mean-Time-To-Recovery (MTTR) +in the event of an outage. There are two steps in the automated recovery process: + +1. Configure snapshots on your current install to backup data +1. Provision a new Terraform Enterprise instance using the latest snapshot + +This guide will walk through both of these steps. + +## Configure snapshots + +Snapshots are taken on the Terraform Enterprise instance. That instance can +have two types of data on it: + +- Terraform Enterprise application data: The core product data such as + run history, configuration history, state history. This data + changes frequently. +- Terraform Enterprise installer data: The data used + to configure Terraform Enterprise itself such as installation type, database + connection settings, hostname. This data rarely changes. + +In the Mounted Disk and External Services operational modes, only +installer data is stored on the instance. Application data +is stored in the mounted disk or in an external PostgreSQL instance. + +Automated snapshots are more effective when using _Mounted Disk_ or +_External Services_ as the amount of backed up data is smaller and +less risky. + +You can configure snapshots in the dashboard under `Console Settings`, in the +`Snapshot & Restore` section. We recommend selecting `Enable Automatic +Scheduled Snapshots`. The interval depends on the operational mode, but we +recommend Daily for Mounted Disk or External Services because the snapshots +contain only configuration data, not application data. + +## Restore a snapshot in a new Terraform Enterprise instance + +## Version Checking + +-> **Note**: `replicatedctl` is located at `/usr/local/bin/replicatedctl`. On some operating systems, `/usr/local/bin` is not in the user's `$PATH`. In these cases, either add `/usr/local/bin` to the path or refer to `replicatedctl` with the full path. + +Using the restore mechanism requires Replicated version 2.17.0 or greater. +You can check the version using `replicatedctl version`. + +## Script + +Below are examples of restore scripts that are run on machine boot. +There are many mechanisms that can run a script on boot (cloud-init, systemd, /etc/init.d). +Which one is used is up to the user. + +This script is presented as an example. Anyone using it needs to understand +what it's doing and is free to modify it to meet any additional needs they have. + +### S3 + +This example uses S3 as the mechanism to store snapshots on a debian-based system. + +``` +#!/bin/bash + +set -e -u -o pipefail + +bucket=your_bucket_to_store_snapshots +region=region_of_the_bucket +access_key=aws_access_key_id +secret_key=aws_secret_access_key + +access="--store s3 --s3-bucket $bucket --s3-region $region --s3-key-id $access_key --s3-secret-key $secret_key" + +# jq is used by this script, so install it. For other Linux distros, either preinstall jq +# and remove these lines, or change to the mechanism your distro uses to install jq. + +apt-get update +apt-get install -y jq + +# Run the installer. + +curl https://install.terraform.io/ptfe/stable | bash -s fast-timeouts + +# Wait for replicated to start before proceeding +until replicatedctl system status --template '{{and (eq .Replicated "ready") (eq .Retraced "ready")}}' | grep -q true; do + sleep 1 + echo "Replicated is not yet ready." +done +echo "Replicated is ready." + +# This retrieves a list of all the snapshots currently available. +replicatedctl snapshot ls $access -o json > /tmp/snapshots.json + +# Pull just the snapshot id out of the list of snapshots +id=$(jq -r 'sort_by(.finished) | .[-1].id // ""' /tmp/snapshots.json) + +# If there are no snapshots available, exit out +if test "$id" = ""; then + echo "No snapshots found" + exit 1 +fi + +echo "Restoring snapshot: $id" + +# Restore the detected snapshot. This ignores preflight checks to be sure the application +# is booted. +replicatedctl snapshot restore $access --dismiss-preflight-checks "$id" + +# Wait until the application reports itself as running. This step can be removed if +# something upstream is prepared to wait for the application to finish booting. +until curl -f -s --connect-timeout 1 http://localhost/_health_check; do + sleep 1 +done + +echo +echo "Application booted!" +``` + +### SFTP + +This example uses sftp to store the snapshots. + +``` +#!/bin/bash + +set -e -u -o pipefail + +key_file=path_to_your_ssh_key +key="$(base64 -w0 "$key_file")" +host=sftp_server_hostname_or_ip +user=user_to_sftp_on_the_remote_server + +access="--store sftp --sftp-host $host --sftp-user $user --sftp-key $key" + +# jq is used by this script, so install it. For other Linux distros, either preinstall jq +# and remove these lines, or change to the mechanism your distro uses to install jq. + +apt-get update +apt-get install -y jq + +# Run the installer. + +curl https://install.terraform.io/ptfe/stable | bash -s fast-timeouts + +# Wait for replicated to start before proceeding +until replicatedctl system status --template '{{and (eq .Replicated "ready") (eq .Retraced "ready")}}' | grep -q true; do + sleep 1 + echo "Replicated is not yet ready." +done +echo "Replicated is ready." + +# This retrieves a list of all the snapshots currently available. +replicatedctl snapshot ls $access -o json > /tmp/snapshots.json + +# Pull just the snapshot id out of the list of snapshots +id=$(jq -r 'sort_by(.finished) | .[-1].id // ""' /tmp/snapshots.json) + +# If there are no snapshots available, exit out +if test "$id" = ""; then + echo "No snapshots found" + exit 1 +fi + +echo "Restoring snapshot: $id" + +# Restore the detected snapshot. This ignores preflight checks to be sure the application +# is booted. +replicatedctl snapshot restore $access --dismiss-preflight-checks "$id" + +# Wait until the application reports itself as running. This step can be removed if +# something upstream is prepared to wait for the application to finish booting. +until curl -f -s --connect-timeout 1 http://localhost/_health_check; do + sleep 1 +done + +echo +echo "Application booted!" +``` + +### Local directory + +This example uses a local directory to store the snapshots. If this is intended to be run +on a brand new system, the local directory would be either mounted block device or a +network filesystem like NFS or CIFS. + +``` +#!/bin/bash + +set -e -u -o pipefail + +path=absolute_path_to_directory_of_snapshots + +access="--store local --path $path" + +# jq is used by this script, so install it. For other Linux distros, either preinstall jq +# and remove these lines, or change to the mechanism your distro uses to install jq. + +apt-get update +apt-get install -y jq + +# Run the installer. + +curl https://install.terraform.io/ptfe/stable | bash -s fast-timeouts + +# Wait for replicated to start before proceeding +until replicatedctl system status --template '{{and (eq .Replicated "ready") (eq .Retraced "ready")}}' | grep -q true; do + sleep 1 + echo "Replicated is not yet ready." +done +echo "Replicated is ready." + +# This retrieves a list of all the snapshots currently available. +replicatedctl snapshot ls $access -o json > /tmp/snapshots.json + +# Pull just the snapshot id out of the list of snapshots +id=$(jq -r 'sort_by(.finished) | .[-1].id // ""' /tmp/snapshots.json) + +# If there are no snapshots available, exit out +if test "$id" = ""; then + echo "No snapshots found" + exit 1 +fi + +echo "Restoring snapshot: $id" + +# Restore the detected snapshot. This ignores preflight checks to be sure the application +# is booted. +replicatedctl snapshot restore $access --dismiss-preflight-checks "$id" + +# Wait until the application reports itself as running. This step can be removed if +# something upstream is prepared to wait for the application to finish booting. +until curl -f -s --connect-timeout 1 http://localhost/_health_check; do + sleep 1 +done + +echo +echo "Application booted!" +``` + +## Airgap recovery considerations + +The instructions above are tailored for the online install method. When restoring on an airgap instance, there are several additional considerations: + +1. The minimum version of Replicated is 2.31.0, rather than 2.17.0. +1. The license file and airgap package must be in place on the new instance prior to restore. The restore process expects to find them in the same locations as they were on the original instance. +1. The snapshot being used must also be from an airgap instance. +1. The `install.sh` script and method used must be from the Replicated airgap installer boostrapper, using the process described for [airgap installation](/terraform/enterprise/deploy/replicated/install/interactive/installer#run-the-installer-airgapped). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/backup-restore.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/backup-restore.mdx new file mode 100644 index 0000000000..9fc0a7f299 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/backup-restore.mdx @@ -0,0 +1,204 @@ +--- +page_title: Backups and Restores - Infrastructure Administration - Terraform Enterprise +description: >- + Use the `/_backup` endpoint to backup and restore all data stored in your installation. Learn how to create and restore backups using the HTTP API. +--- + +# Terraform Enterprise Backups and Restores + +Terraform Enterprise provides an API to backup and restore all of its application data. + +The backup and restore API is separate from the Terraform Enterprise application-level APIs. As such, a separate authorization token is required to use the backup and restore API. See [Authentication](#authentication) below for more details. + +Using the backup and restore API is the only supported way to migrate between operational modes (mounted disk, external services). + +> **Note**: We do not recommend using the backup and restore API to maintain periodic Terraform Enterprise application data backups. For best practices, refer to our recommended patterns covering the [backup](/terraform/tutorials/recommended-patterns/pattern-backups) and [restore](/terraform/tutorials/recommended-patterns/pattern-recovery) processes. + +## About Backups and Restores + +The backup and restore API backs up all of the data stored in a Terraform Enterprise installation, including both the blob storage and the PostgreSQL database. It does not back up the installation configuration. This backup can then be restored to a new installation of Terraform Enterprise. + +Note the following when using the backup and restore API: + +- The version of Terraform Enterprise cannot be changed between a backup and restore. A backup taken from one version of Terraform Enterprise cannot be restored to an installation running a different version of Terraform Enterprise. +- The version of PostgreSQL being used cannot be changed between a backup and restore. A backup taken from a Terraform Enterprise installation using one version of PostgreSQL cannot be restored to an installation using a different version of PostgreSQL. +- Terraform Enterprise internally uses PostgreSQL v14, so customers using PostgreSQL v15 cannot use the [backup and restore API](/terraform/enterprise/deploy/manage/backup-restore). Instead, use cloud-native tools, or manually backup and restore your database with `pg_dump` and `pg_restore`. +- The Terraform Enterprise installation that will be restored to must be a new, + running installation with no existing application data. +- The backup and restore API times out after 5000 seconds (83.3 minutes). If you have a lot of + data in the object store, use [`skip-object-storage`](#request-body) to + finish the backup in time. Then after you restore the backup, manually move your object store data. See this + [support article](https://support.hashicorp.com/hc/en-us/articles/10536697730323-Migrate-TFE-from-Mounted-Disk-to-External-Services-mode-with-Backup-Restore-API) for details. +- Once a restore is completed, the Terraform Enterprise application will need to be restarted before it can use the restored data. + +See also: + +- [Data Security](/terraform/enterprise/deploy/replicated/architecture/system-overview/data-security) for details about the contents of Terraform Enterprise's blob storage and PostgreSQL database. + +### Authentication + +The backup and restore API uses a separate authorization token which can be found on the settings dashboard (`https://:8800/settings`) near the bottom of the page: + +![Screenshot: the TFE install dashboard, with the API token visible](/img/docs/token.png) + +If the Replicated console dashboard is unavailable, execute `replicatedctl app-config export --template '{{.backup_token.Value}}'` from the TFE node shell to get the backup API authorization token. + +-> **Note:** This authorization token is specific to the Terraform Enterprise installation. As a result, the authorization token used to create a backup may be different than the authorization token used to perform a restore. Please ensure you are using the correct authorization token when performing a backup or restore operation. + +The backup and restore API is separate from the Terraform Enterprise application-level APIs and cannot be accessed with Terraform Enterprise user, team, or organization API tokens. + +To use this authorization token with the backup and restore API, pass the `Authorization: Bearer ` header in your API requests. + +~> **Important:** Since this authorization token can access all of the data in a Terraform Enterprise installation, protect it very carefully. + +### Security and Encryption + +Terraform Enterprise uses HashiCorp Vault to encrypt and decrypt its data. The Vault encryption keys that are used to encrypt and decrypt this data are not preserved during a backup or restore. Instead, during a backup, the data is decrypted by Vault and then re-encrypted using a password provided by you, resulting in an encrypted backup blob. During a restore, the same password that you provided during the backup must be used to decrypt the data before it is re-encrypted with the new Terraform Enterprise installation's Vault encryption keys. + +The backup and restore API expect this password to be provided as a JSON object with a `password` property within the request payload. The value for the `password` property can be any valid string. Here's what an example JSON object looks like. + +```json +{ + "password": "befit-brakeman-footstep-unclasp" +} +``` + +~> **Important:** The same password that was provided during backup must be provided during restore. This password can be used to access all of the data that was backed up. Please protect it very carefully. + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +## Creating a Backup + +`POST /_backup/api/v1/backup` + +To initiate a backup, make a POST request to the backup endpoint on a running Terraform Enterprise installation. + +The response to this request will be an encrypted binary blob containing all of your Terraform Enterprise data. When using this endpoint, please: + +- Remember to specify an output file for the encrypted backup blob. +- Be prepared to download and store many gigabytes of data to the filesystem of whichever machine the request is sent from. For best performance and to avoid disconnections, we recommend sending this request from a server colocated with the Terraform Enterprise installation rather than from a workstation. +- Treat this encrypted backup blob as sensitive data and ensure it is stored securely. +- Remember the password that was used to encrypt this backup blob. + +| Status | Response | Reason | +| ------- | ------------------ | ----------------------------- | +| [200][] | Binary backup blob | Successfully created a backup | +| [400][] | (none) | Invalid request | +| [500][] | (none) | Internal server error | + +~> **Important:** A successful backup **must** return `200`. If `200` is not returned and the call silently closes, the backup blob may be incomplete, resulting in data loss. + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------- | ------ | ------- | ---------------------------------------------------------- | +| `password` | string | | The password used to encrypt the backup blob. | +| `skip_object_storage` | bool | `false` | Whether or not to skip backing up the object storage data. | + +### Sample Payload + +```json +{ + "password": "befit-brakeman-footstep-unclasp" +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --request POST \ + --data @payload.json \ + --output backup.blob \ + https:///_backup/api/v1/backup +``` + +## Restoring a Backup + +`POST /_backup/api/v1/restore` + +Before restoring, you must first create a new Terraform Enterprise installation. + +-> **Note:** The authorization token used to restore the backup is specific to the Terraform Enterprise installation. If restoring to a separate Terraform Enterprise installation, the authorization token will be different for the restore than it was for the backup. See [Authentication](#authentication) above for more details. + +Once the Terraform Enterprise application is up and running, you can initiate a restore by making a POST request to the restore endpoint. + +Be prepared to upload many gigabytes of data from the filesystem of whichever machine the request is sent from. For best performance and to avoid disconnections, we recommend sending this request from a server colocated with the Terraform Enterprise installation rather than from a workstation. + +Once the restore is complete, you must **restart the application.** The application will not restart automatically. There are two ways to do this: + +- Log into the install dashboard and stop, then start the application. +- From the CLI, run `replicatedctl app stop`, then run `replicatedctl app start`. + +| Status | Response | Reason | +| ------- | -------- | ------------------------------ | +| [200][] | (none) | Successfully restored a backup | +| [400][] | (none) | Invalid request | +| [500][] | (none) | Internal server error | + +### Request Body + +This POST endpoint requires the following form fields which must be provided as `multipart/form-data`. + +| Form field | Description | +| ---------- | ---------------------------------------------------------------------------------- | +| `snapshot` | An encrypted backup blob downloaded from the Terraform Enterprise backup endpoint. | +| `config` | A JSON file containing a JSON object. See the table below. | + +The JSON file used in the `config` form field above must contain a JSON object with the following properties. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------- | ------ | ------- | --------------------------------------------- | +| `password` | string | | The password used to decrypt the backup blob. | + +### Sample Payload + +```json +{ + "password": "befit-brakeman-footstep-unclasp" +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --request POST \ + --form config=@payload.json \ + --form snapshot=@backup.blob \ + https:///_backup/api/v1/restore +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/consolidated-services.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/consolidated-services.mdx new file mode 100644 index 0000000000..c0e61cd852 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/consolidated-services.mdx @@ -0,0 +1,125 @@ +--- +page_title: Consolidated Services - Infrastructure Administration - Terraform Enterprise +description: >- + Terraform Enterprise is adopting a simplified architecture where all server services are consolidated into a single container named `terraform-enterprise`. +--- + +# Terraform Enterprise Consolidated Services Architecture + +Terraform Enterprise is adopting a simplified architecture where all server +services are consolidated into a single container called +`terraform-enterprise`. This change improves +how you install and operate Terraform Enterprise, and includes an immediate +security benefit of running containers as a non-root user. This architecture is the default +configuration in the v202309-1 release, and you can disable it using the `consolidated_services_enabled` setting until v202401-1, +when we will remove the setting. + +## Changes + +When `consolidated_services_enabled` is enabled: + +- Terraform Enterprise services run inside the `terraform-enterprise` + container. +- Containers run as a non-root user. + +- When log-forwarding is not enabled, all service logs are logged to STDOUT, are in `json-file` format and include a new `component` attribute that specifies which Terraform Enterprise service emitted the log. + + The log below is an example of a log from the `atlas` component and is in escaped JSON format. + ```JSON + {"component":"atlas","log":"2023-09-14 19:04:42 [INFO] [d6e4e6db-06b6-4297-b1ff-ae310ebee25e] [dd.service=atlas + dd.trace_id=4001067029455957720 dd.span_id=0] {\"method\":\"GET\",\"path\":\"/_health_check\",\"format\":\"html\", + \"status\":200,\"allocations\":503,\"duration\":1.26,\"view\":0.32,\"db\":0.0,\"dd\":{\"trace_id\": + \"4001067029455957720\",\"span_id\":\"0\",\"env\":\"\",\"service\":\"atlas\",\"version\":\"\"},\"ddsource\": + [\"ruby\"],\"uuid\":\"d6e4e6db-06b6-4297-b1ff-ae310ebee25e\",\"remote_ip\":\"127.0.0.1\",\"request_id\": + \"d6e4e6db-06b6-4297-b1ff-ae310ebee25e\",\"user_agent\":\"Load Balancer Agent\",\"user\":null,\"auth_source\":null}"} + ``` + + The log below is an example of a log from the `sidekiq` component and is a JSON formatted log. + ```JSON + {"component":"sidekiq","log":"2023-09-14 19:04:19 [INFO] msg=Worker finish worker=AgentStatusWorker"} + ``` + + The log below is an example of an Audit Log from the `atlas` component and is in JSON escaped format. + + ```JSON + {"component":"atlas","log":"2023-09-14 19:59:36 [INFO] [9787b874-565a-4cd1-9146-f9e89a6286f4] [dd.service=atlas + dd.trace_id=1839403271971964936 dd.span_id=0] [Audit Log] {\"resource\":\"workspace\",\"action\":\"create\", + \"resource_id\":\"ws-8RoTSc9iow6JE6Nt\",\"organization\":\"banana\",\"organization_id\":\"org-DPfZszgSorjbaF9M\", + \"actor\":\"manage\",\"timestamp\":\"2023-09-14T19:59:36Z\",\"meta\":{\"project_id\":\"prj-f54CoqSE8X9sXd5F\"}, + \"actor_ip\":\"24.17.65.143\"}"} + ``` + + The following components emit log messages in escaped JSON format: + + - `archivist` + - `task-worker` + - `slug-ingress` + - `outbound-http-proxy` + - `terraform-registry-api` + - `terraform-state-parser` + - `terraform-registry-worker` + + +If using the log-forwarding feature, your service logs are sent to your configured log aggregation service and are in the format that the `fluent-bit` plugin uses. + +In previous releases, the `container_name` attribute contained the name of the Terraform Enterprise service that emitted the log. In the v202309-1 release and beyond, the `container_name` attribute is `terraform-enterprise`, and the `component` metadata attribute logs the name of the service responsible for emitting that log. +For example, prior to v202309-1 your log metadata resembles: + ``` + service: terraform_enterprise + container_name: tfe-atlas + component: n/a + ``` + +After v202309-1, the log metadata resembles: + ``` + service: terraform_enterprise + container_name: terraform_enterprise + component: atlas + ``` + + +## What hasn’t changed? + +Terraform runs continue to execute in isolated, short-lived containers. + +### How can I disable consolidated services? + +1. Disable the `consolidated_services_enabled` setting. + + ``` + replicatedctl app-config set consolidated_services_enabled --value 0 + ``` + +1. Restart Terraform Enterprise. + + ```sh + replicatedctl app stop + + replicatedctl app status + + replicatedctl app start + ``` + +## Frequently Asked Questions (F.A.Q) + +### What should I test to verify if I'm impacted by this change? + +We advise users to evaluate the impact this will have on your monitoring and +log forwarding implementation. + +All server services are now included in a single container. If you are +monitoring container metrics, please note that you will have fewer containers +reporting information. Run containers are not impacted by this change, they +remain separate and short-lived. + +Service logs have been consolidated into a single log stream. + +### Where should I seek help with issues? + +Contact [HashiCorp support](/terraform/enterprise/deploy/troubleshoot/contact-support) for help with any issues. + +### Will this always be an optional architecture? + +No. In v202401-1, consolidated services will become the default and only +option. + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/index.mdx new file mode 100644 index 0000000000..de007ab141 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/index.mdx @@ -0,0 +1,21 @@ +--- +page_title: Infrastructure administration overview +description: >- + Learn about administrating Terraform Enterprise infrastructure deployed to the legacy Replicated platform. +--- + +# Infrastructure administration overview for Replicated deployments + +This topic contains overview information administrating the Terraform Enterprise infrastructure when deployed to the legacy Replicated runtime. For information about administration for non-Replicated runtimes, including Docker, Kubernetes, Nomad, OpenShift, and Podman, refer to [Manage Terraform Enterprise deployment overview](/terraform/enterprise/deploy/manage). + +## Workflows + +You can perform the following actions: + +- [Use the CLI](/terraform/enterprise/deploy/replicated/administration/infrastructure/admin-cli) +- [Enable automated recovery](/terraform/enterprise/deploy/replicated/administration/infrastructure/automated-recovery) +- [Back up and restore your deployment](/terraform/enterprise/deploy/replicated/administration/infrastructure/backup-restore) +- [Learn about the consolidated services architecture](/terraform/enterprise/deploy/replicated/administration/infrastructure/consolidated-services) +- [Migrate to `external` mode from `disk` mode](/terraform/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration) +- [Upgrade your installation](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) +- [Migrate worker images to agents](/terraform/enterprise/deploy/replicated/administration/infrastructure/worker-to-agent-migration) \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration.mdx new file mode 100644 index 0000000000..de660ca9c3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration.mdx @@ -0,0 +1,139 @@ +--- +page_title: Migrating from Mounted Disk Mode to External Services Mode - Infrastructure Administration - Terraform Enterprise +description: >- + Migrating from Mounted Disk Mode to External Services Mode +--- + +# Migrating from `disk` to `external` mode + +You must choose an operational mode before you install and deploy Terraform Enterprise. To change the operational mode, you must backup the data of your Terraform Enterprise installation and restore it to a new one. If you currently use the [`disk` operational mode](/terraform/enterprise/deploy/reference/configuration#disk) and are migrating to a [non-Replicated runtime](/terraform/enterprise/deploy) other than `disk` mode on Docker, you must first migrate to `external` mode. + +## Create a Backup + +To create a backup, retrieve the backup API token from your Terraform Enterprise installation's settings page. Store this token in an environment variable. + +```shell-session +$ export TOKEN= +``` + +Next, create a file named `payload.json` that includes your Terraform Enterprise encryption password. + +```json +{ + "password": "" +} +``` + +Optionally, if you have a large number of objects in storage which is causing your backup to become very large, you can skip the backup of the object storage by adding the `skip_object_storage` field to the `payload.json` file. + +```json +{ + "password": "", + "skip_object_storage": true +} +``` + +Finally, create the an encrypted backup file named `backup.blob` in the current directory. + +```shell-session +$ curl \ + --header "Authorization: Bearer ${TOKEN}" \ + --request POST \ + --data @payload.json \ + --output backup.blob \ + https:///_backup/api/v1/backup +``` + +## Prepare the New environment + +Create a new Terraform Enterprise installation. The new installation must meet the following requirements: + +1. The [`TFE_OPERATIONAL_MODE`](/terraform/enterprise/deploy/reference/configuration#tfe_operational_mode) configuration must be set to `external` or `active-active`. +1. It is configured with the same encryption password as the instance that you created the backup from. +1. The PostgreSQL database version matches the version your mounted disk installation uses. + +## Restore the Backup + +Retrieve the backup API token from your new Terraform Enterprise installation's settings page. Store this token in an environment variable. + +```shell-session +$ export TOKEN= +``` + +Use the same `payload.json` and `backup.blob` files to restore the backup. + +```shell-session +$ curl \ + --header "Authorization: Bearer ${TOKEN}" \ + --request POST \ + --form config=@payload.json \ + --form snapshot=@backup.blob \ + https:///_backup/api/v1/restore + ``` + +## Upload to Object Store (Optional) + +If you set `skip_object_storage` to true in your `payload.json` file, you must separately upload your local disk storage to your S3-compatible object store. + +SSH into the old Terraform Enterprise instance and navigate to the configured mounted disk path. If you do not know the mounted disk path, you can retrieve it using the `replicatedctl` command. + +```shell-session +$ replicatedctl app-config export | grep "disk_path" -A1 +``` + +Navigate to the mounted disk path. + +```shell-session +$ cd +``` + +Next, set your AWS credentials as environment variables. These credentials must have access to write to S3. + +```shell-session +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export REGION= +export BUCKET= +``` + +Next, upload the contents of each directory in the `/aux/archivist` directory. + +~> NOTE: Some directories may not exist in your installation. Ensure that you upload all contents of the `archivist` directory to your object storage and that you prefix each directory with `archivist`. + +```shell-session +aws s3 cp --recursive terraform s3://${BUCKET}/archivistterraform + +aws s3 cp --recursive sentinel s3://${BUCKET}/archivistsentinel + +aws s3 cp --recursive plan-export s3://${BUCKET}/archivistplan-export + +aws s3 cp --recursive policy-set-versions s3://${BUCKET}/archivistpolicy-set-versions +``` + +## Restart Terraform Enterprise + +SSH into the new Terraform Enterprise instance and stop the Terraform Enterprise application. + +```shell-session +$ replicatedctl app stop +``` + +Watch the status of the Terraform Enterprise application until the `State` is `stopped`. + +```shell-session +$ watch replicatedctl app status +``` + +Once it has stopped, start Terraform Enterprise application. + +```shell-session +$ replicatedctl app start +``` + +Watch the status of the Terraform Enterprise application until the `State` is `started`. + +```shell-session +$ watch replicatedctl app status +``` + +Once the Terraform Enterprise application is started, you have successfully migrated to external services. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/index.mdx new file mode 100644 index 0000000000..dfd5025577 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/index.mdx @@ -0,0 +1,54 @@ +--- +page_title: Upgrade Replicated deployment overview +description: This overview describes how to upgrade Terraform Enterprise deployments, including air-gapped Terraform Enterprise deployments, that run on Replicated. +--- + +# Upgrade Replicated deployment overview + +This topic provides an overview of how to upgrade Terraform Enterprise deployments that run on the Replicated platform. For instructions on upgrading Terraform Enterprise deployed to other runtimes, refer [Upgrade Terraform Enterprise](/terraform/enterprise/deploy/manage/upgrade). + + +

The Replicated deployment option is limited to customers who purchased Terraform Enterprise before January 2024. Terraform Enterprise supports new deployment options and will end support for the Replicated Native Scheduler option.

+ +

The final Replicated release of Terraform Enterprise will be in March 2025. HashiCorp will support this release until April 1, 2026.

+ +

To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by November 2024. For more information, refer to Terraform Enterprise deployment overview or contact your HashiCorp account representative.

+ + +## Workflows + +We recommend [contacting HashiCorp support](/terraform/enterprise/deploy/troubleshoot/contact-support) or your account team before starting on an upgrade journey if you have any questions or concerns. Complete the following steps to upgrade Terraform Enterprise: + +1. Plan your upgrade: There are several preparatory actions you should take to plan your upgrade. For example, you should review release notes for versions along your upgrade path so that you are aware of required releases and new or deprecated features and other updates may affect your existing workflows. Refer to [Plan your upgrade](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades/plan) for details. +1. Perform the upgrade steps: Verify that you meet the requirements and follow the instructions for upgrading an Internet-connected or air-gapped deployment. Refer to [Upgrade your Replicated deployment upgrade](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades/upgrade) for details. + +## Upgrade duration +You can expect an upgrade for a single Terraform Enterprise instance to last 15-30 minutes. In rare cases, a release may include synchronous database migrations that could extend the upgrade duration for large-scale deployments. + +To help you prepare for an extended upgrade, refer to the release notes for the version you are upgrading to. For example, the following release notes describe potential extended upgrades: + +- [v202406-1 release notes](/terraform/enterprise/releases/2024/v202406-1): The upgrade appears to stall when the data directory contains 1 TB or more of data and Terraform Enterprise is in `disk` mode. +- [v202210-1 release notes](/terraform/enterprise/releases/2022/v202210-1): The migration may add two minutes per 5,000 organizations. + +When skipping releases, be sure to review release notes for all skipped releases for a cumulative list of all breaking changes, known issues, fixes, and features added between your current and target version. + +## Releases +Refer to the [releases documentation](/terraform/enterprise/releases) for details about new releases. We update the releases documentation every time we release a new version. + +Unless a release is delayed or pushed up due to unseen circumstances, we release a new version of Terraform Enterprise once a month. The target release date for the next version appears at the top of the release page. You can also monitor [our forum](https://discuss.hashicorp.com/tags/c/release-notifications/57/terraform-enterprise) for release updates. + +The first release of each month has a `-1` at the end of the version number. The release usually includes application changes, such as new functionality, bug fixes, and performance enhancements. We increment the number at the end of the version as we release subsequent versions. These versions are generally patches that resolve a moderate to high severity issue. Some months do not include a patch release. + +### Required releases +You cannot skip a release that contains critical updates, such as an upgrade or breaking change to an internal dependency. For example, if your current release is `v202206-1` and you want to upgrade to `v202210-1`, but `v202207-2*` is required, you must first upgrade to `v202207-2*` before performing another upgrade from `v202207-2*` to `v202210-1`. + +We denote required releases with an asterisk next to the version number in the [releases documentation](/terraform/enterprise/releases), for example, `v202207-2*`. Releases without an asterisk are optional and you can skip them when jumping multiple releases. We mark releases as required if they contain changes that require a full application startup before proceeding to a further release. + +## Terraform Enterprise environment +Upgrading may require a change to the stack of technologies that supports your Terraform Enterprise deployment. The environment may include the following components: + +- Cloud or platform provider the host is running on, such as AWS or VMware +- Host, such as the EC2 instance +- Operating system, such as RHEL 7.6 +- Postgres version +- Redis version diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/prepare.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/prepare.mdx new file mode 100644 index 0000000000..e910ec953a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/prepare.mdx @@ -0,0 +1,101 @@ +--- +page_title: Prepare your Terraform Enterprise environment for a version upgrade +description: This overview describes how to upgrade Terraform Enterprise deployments, including air-gapped Terraform Enterprise deployments, that run on Replicated. +--- + +# Prepare your environment for a version upgrade + +This topic describes how to prepare your Terraform Enterprise environment for a version upgrade when deployed to the Replicated platform. For instructions on upgrading Terraform Enterprise deployed to other runtimes, refer [Upgrade Terraform Enterprise](/terraform/enterprise/deploy/manage/upgrade). + + +

The Replicated deployment option is limited to customers who purchased Terraform Enterprise before January 2024. Terraform Enterprise supports new deployment options and will end support for the Replicated Native Scheduler option.

+ +

The final Replicated release of Terraform Enterprise will be in March 2025. HashiCorp will support this release until April 1, 2026.

+ +

To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by November 2024. For more information, refer to Terraform Enterprise deployment overview or contact your HashiCorp account representative.

+ + +## Overview + +You should create a plan for upgrading your Terraform Enterprise deployment to minimize potential issues. Complete the following steps to prepare for your upgrade: + +1. **Thoroughly review release information**: The release notes contain critical information about each release, including required versions along the upgrade path and breaking changes. When skipping releases, be sure to review release notes for all skipped releases for a cumulative list of all breaking changes, known issues, fixes, and features added between your current and target version. +1. **Verify your Replicated license**: You must have an active license to complete the upgrade. +1. **Configure log forwarding**: If the upgrade fails, forwarding logs to a persistent storage system can help you diagnose the problem. +1. **Back up your system**: Create backups of stateful data, configuration files, and other artifacts so that you are prepared in case you experience issues during the upgrade. +1. **Test against a dev/test environment**: Create a mirror of your production environment so that you can safely test your upgrade path. Test environments do not count against your Terraform Enterprise license. + +### Pre-upgrade checklist +Use the following checklist to help you prepare for upgrading your Terraform Enterprise deployment: + +- [ ] OS version is supported at my target version. +- [ ] Postgres version is supported at my target version. +- [ ] Redis version is supported at my target version if running in `active-active` mode. +- [ ] Docker version is supported at my target version. +- [ ] I know the required releases between my current and target version. +- [ ] I understand that I will have to fully start the application at each required release between my current and target version +- [ ] I have reviewed the breaking changes in all releases between my current and target version and have planned accordingly. +- [ ] I have reviewed the deprecated features in all releases between my current and target version and planned accordingly. +- [ ] I have configured Terraform Enterprise to forward logs from my installation so that they are still available if the installation restarts. +- [ ] I have tested my upgrade path in a test environment that mimics my production environment. +- [ ] I have created a backup of my Terraform Enterprise data. +- [ ] I have created a backup of my Terraform Enterprise configuration. Store the Terraform Enterprise configuration in a `settings.json` file. You can use the Replicated snapshot feature to create the backup. +- [ ] I have created a backup of my Replicated configuration. Store the Replicated configuration in a `replicated.conf` file. You can use the Replicated snapshot feature to create the backup. + +## Review release information +Refer to the [releases documentation](/terraform/enterprise/releases) for details about new releases. Focus on the following aspects of the releases in your upgrade path: + +### Updates to functionality +The Highlights, Features, and Improvements sections in the release notes describe information about changes between your current release and the target release so that you can adjust workflows accordingly. + +### Required releases +Note any required releases between your current release and the target release. The release notes denote required releases with an asterisk. + +You must include required releases as part of the upgrade path to your target version. You must also start the application after upgrading to a required version before proceeding with the upgrade. + +Refer to the [releases overview page](/terraform/enterprise/releases) and click the **Replicated** tab for additional details. + +### Breaking changes +Check the release notes for all versions along your upgrade path for breaking changes. +Failing to take action associated with a breaking change may cause upgrade failures or disruptions to core application workflows. + +The release documentation describes breaking changes, if any, for each release. For example, the [v202210-1 release](/terraform/enterprise/releases/2022/v202210-1) includes a breaking change for customers on Postgres v10. + +## Verify the Replicated license +An expired Replicated license can cause an installation to fail. Before upgrading, ensure your license is valid. If your license is expired, contact your HashiCorp account manager. Refer to the [licensing documentation](/terraform/enterprise/deploy/replicated/administration/license/update-tfe-license) for details. + +## Configure log forwarding +We recommend configuring Terraform Enterprise to forward logs to a persistent storage system. Log forwarding prevents you from losing log information if an error occurs during an upgrade and the system restarts. If you do not have your own log forwarding toolstack, you can use the embedded Fluentbit feature. + +Refer to the following topics for instructions on how to enable log forwarding with Fluentbit: + +- [Terraform Enterprise Log Forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging) +- [Forward Terraform Enterprise logs to Datadog](/terraform/tutorials/enterprise/tfe-log-forwarding) + +## Back up your system +We recommend regularly backing up all stateful services and configuration files, as well as external services, such as Postgres, object storage, `replicated.conf`, and `settings.json` so that you can recover in the unlikely event that Terraform Enterprise encounters an edge case issue. + +Refer to the following topics for instructions: + +- [Terraform Enterprise backup - recommended pattern tutorial](https://developer.hashicorp.com/terraform/tutorials/recommended-patterns/pattern-backups) +- [Terraform Enterprise Backups and Restores](/terraform/enterprise/deploy/replicated/administration/infrastructure/backup-restore) + +## Test your upgrade plan +We strongly recommend that you create a dedicated test environment for testing your upgrade plan before scheduling an upgrade in production. You can use the same Terraform Enterprise license in your test environment as your production environment. Test environments do not count against your workspace allowance. + +The following components and configuration in your test environment should match your production environment as closely as possible: + +- Environment dependencies: + - Cloud platform, for example AWS + - Host type, such as EC2 instance with the same resource allocations + - Operating system version + - Postgres version + - Redis version if Terraform Enterprise is in `active/active`mode + - Docker version +- Installed Terraform Enterprise version +- Terraform Enterprise configuration files: + - `replicated.conf` + - `settings.json` +- Replicated version + +Dev/test environments should not share external services with your production environment, including Postgres, object storage, and Redis. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/upgrade.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/upgrade.mdx new file mode 100644 index 0000000000..753616510f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/upgrades/upgrade.mdx @@ -0,0 +1,188 @@ +--- +page_title: Upgrades - Infrastructure Administration - Terraform Enterprise +description: >- + Learn how to upgrade Terraform Enterprise deployments, including air-gapped Terraform Enteprise deployments, that run on Replicated. +--- + +# Upgrade Terraform Enterprise deployed to Replicated + +This topic describes how to upgrade Terraform Enterprise deployed to the Replicated platform. For instructions on upgrading Terraform Enterprise deployed to other runtimes, refer [Upgrade Terraform Enterprise](/terraform/enterprise/deploy/manage/upgrade). + + + +

The Replicated deployment option is limited to customers who purchased Terraform Enterprise before January 2024. Terraform Enterprise supports new deployment options and will end support for the Replicated Native Scheduler option.

+ +

The final Replicated release of Terraform Enterprise will be in March 2025. HashiCorp will support this release until April 1, 2026.

+ +

To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by November 2024. For more information, refer to Terraform Enterprise deployment overview or contact your HashiCorp account representative.

+ + +## Overview + +Complete the following steps to upgrade your Terraform Enterprise deployment: + + +1. Creata a backup of your application settings so that you can restore if an issue appears during the upgrade. +1. Prune dangling resources to clear space on the host for the upgraded images. +1. Use either the Replicated console or CLI to perform the upgrade. The instructions for either mechanism depends on whether Terraform Enterprise has Internet connectivity or is air-gapped. +1. You can track upgrade progress from the Replicated admin console or using the Replicated CLI. If you experience issues during the upgrade, refer to the [troubleshooting instructions](#troubleshooting). +1. Complete any [post-upgrade tasks](#post-upgrade-tasks). + +Do not manually restart the application during the upgrade. Doing so will cause upgrade failure and loss of logs required to diagnose potential upgrade issues. + +### Multi-node deployments +This topic describes upgrading single-node deployment of Terraform Enterprise in `external` mode. Refer to the following topics for information about upgrading multi-node deployments in `active-active`: + +- [Terraform Enterprise Active/Active](/terraform/enterprise/deploy/replicated/install/automated/active-active) +- [Terraform Enterprise Admin CLI Commands](/terraform/enterprise/deploy/replicated/administration/infrastructure/admin-cli) + + +## Requirements + +1. Complete the steps described in [Prepare your environment for a version upgrade](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades/prepare) before beginning the upgrade process. +1. Review the following Terraform Enterprise requirements to ensure that your environment is supported: + + - [TLS requirements](/terraform/enterprise/deploy/replicated/requirements/credentials) + - [Hardware](/terraform/enterprise/deploy/replicated/requirements/hardware) + - [Operating system](/terraform/enterprise/deploy/replicated/requirements/os-specific/supported-os) + - [PostgreSQL](/terraform/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements) + - [Network](/terraform/enterprise/deploy/replicated/requirements/network) + - [Docker Engine](/terraform/enterprise/deploy/replicated/requirements/docker_engine) + +1. Review the [upgrading and patching information](/terraform/enterprise/deploy/replicated/administration/infrastructure/admin-cli#upgrading-tfe-or-patching-tfe-node-instances) for your Terraform Enterprise active/active architecture. + +1. Create a backup copy of the storage prior to upgrading your instance. Backup and restore responsibility varies depending on your Terraform Enterprise [operation mode](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability#operation-modes). + +## Back up your application settings + +Connect to the Terraform Enterprise host machine using SSH and run the following command to export a copy of current application settings: + +```shell-session +$ replicatedctl app-config export --hidden > backup_settings.json +``` + +## Prune dangling resources + +Run the following command to manually prune dangling Docker resources to clear space for upgraded images. + + ``` + docker container prune -f + docker volume prune -f + ``` + +## Upgrade Internet-connected deployments + + + + +1. Open the installer dashboard at `https://:8800/dashboard` in your browser. +1. Click **Check Now**. Terraform recognizes the new version. +1. Click **View Update**. +1. Review the release notes and then click **Install Update**. + + + + +1. Connect to the Terraform Enterprise host machine using SSH. +1. Fetch the versions of Terraform Enterprise. + + ``` + $ replicatedctl app-release ls --fetch + ``` + +1. Upgrade to the latest version of Terraform Enterprise. + + ``` + $ replicatedctl app-release apply + ``` + + Alternatively, upgrade to a specific version of Terraform Enterprise. + + ``` + $ replicatedctl app-release apply --sequence "504" + ``` + + + + +## Upgrade air-gapped deployments + + + + +1. Open the installer dashboard at `https://:8800/dashboard` in your browser. +1. Check the **Update Path** field in the console settings for you instance to determine the update path where the installer should look for new `.airgap` packages. +1. Download the new `.airgap` package to the instance and place it at the location specified in the **Update Path** field. +1. From the installer dashboard, click **Check Now**. Terraform recognizes the new version. +1. Click **View Update**. +1. Review the release notes and then click **Install Update**. + + + + + +1. Connect to the Terraform Enterprise host machine using SSH. + +1. Print the `AirgapPackagePath`. + + ``` + $ replicatedctl params export --template '{{.AirgapPackagePath}}' + ``` + +1. On the Terraform Enterprise host machine, upload the desired airgap packages into the `AirgapPackagePath`. + +1. Fetch the versions of Terraform Enterprise from the uploaded airgap packages. + + ``` + $ replicatedctl app-release ls --fetch + ``` + +1. List the available versions of airgap packages for the upgrade. + + ``` + $ replicatedctl app-release ls + ``` + +1. Upgrade to the latest version of the available airgap packages. + + ``` + $ replicatedctl app-release apply + ``` + + Alternatively, upgrade to a specific version, using one of the options listed in the output of the previous step. + + ``` + $ replicatedctl app-release apply --sequence "504" + ``` + + + + +## Track upgrade progress + +To track progress from the UI, check the **Status** widget on the Replicated admin console. The **Status** widget is not available for deployments in `active-active` mode. + +Run the `replicatedctl app status` command to track progress from the CLI. + +## Post-upgrade tasks + +Complete the following tasks if you are stopping at a required release: + +1. Fully start the application before proceeding to your next release. +1. Run the `tfe-admin health-check` command to verify that service connectivity has successfully re-established. + +## Troubleshooting + +This section describes potential causes of issues during or after an upgrade. + +### Upgrade fails to proceed +If you suspect your upgrade is stuck, check log messages in `tfe-migrations`. Migrations can take longer than usual and extend the upgrade window. + +If there are no migrations in progress and the upgrade is still not completed in a timely manner, contact support. + +Do not manually restart the application during the upgrade. Doing so will cause upgrade failure and loss of logs required to diagnose potential upgrade issues. + +### Missing or improper functionality +The functionality may have been deprecated in a version in your upgrade path. The functionality may also be related to deprecated or removed support for an operating system, Postgres version, or other dependency. Refer to the release notes for information about deprecated, removed, or replaced functionality and for potential workarounds. + +Once a functionality is removed or a dependency dropped, Terraform Enterprise no longer officially supports it. As a result, the functionality or dependency is no longer covered in the release regression testing suite. If the removed feature or dependency is the cause of issues related to upgrades or operability, you may be required to migrate off the feature or dependency to get help from HashiCorp support. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/worker-to-agent-migration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/worker-to-agent-migration.mdx new file mode 100644 index 0000000000..7a719de524 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/infrastructure/worker-to-agent-migration.mdx @@ -0,0 +1,184 @@ +--- +page_title: >- + Migrate from Alternative Worker Images to Custom Agents - v202302-1 +description: Learn how to migrate from using alternative worker images to custom agents. Available as of Terraform Enterprise v202302-1. +--- + +# Migrate Alternative Worker Images to Agents: v202302-1 + +## Summary + +Terraform Enterprise v202302-1 introduced the `agent` run pipeline mode which +changes the container image used to perform Terraform runs. The previous run +pipeline mode is now referred to as the `legacy` run pipeline mode. + +If you currently use the _default_ image, you do not need to take action. +Terraform Enterprise will automatically migrate you to the new default agent +image when you adopt v202302-1 or later. + +If you currently use a [legacy custom +image](/terraform/enterprise/deploy/replicated/install/interactive/installer#legacy) Terraform +Enterprise will continue using your legacy custom image until you migrate to an +agent custom image and enable the `agent` run pipeline mode. Before adopting +v202306-1, you must [build an agent custom +image](/terraform/enterprise/deploy/replicated/install/interactive/installer#agent). If your +legacy custom image also [executes custom +scripts](/terraform/enterprise/deploy/replicated/install/interactive/installer#executing-custom-scripts), +you must update migrate your customization [agent +hooks](/terraform/cloud-docs/agents/hooks) instead. + +Terraform Enterprise will stop supporting legacy custom images in v202306-1. + +Continue reading to determine if this change impacts you and what action to +take. + +## What are alternative worker images? + +An alternative worker image is the [custom +image](/terraform/enterprise/deploy/replicated/install/interactive/installer#custom-image) +Terraform Enterprise uses to perform Terraform runs. + +## What is changing and why? + +We are replacing three components of the run pipeline, `terraform-build-worker`, +`terraform-build-manager`, and `tfe-rabbitmq` with local HCP Terraform/Enterprise +agents. If you use an alternative worker image to execute custom logic within +the run lifecycle, you will need to migrate that logic to an agent custom image. + +Like Terraform runs that use alternative worker images, runs that use custom agents will still execute in isolated, +short-lived [Docker +containers](/terraform/enterprise/deploy/replicated/architecture/system-overview/security-model#terraform-enterprise-isolates-terraform-operations-via-docker-containers). +This change does not affect the Terraform Runs API and UI. + +This change is part of an ongoing effort to refresh the architecture of +Terraform Enterprise, improve performance and reliability of runs, and support +new application-level features. Some immediate benefits of this change include: + +- The run pipeline contains fewer components, making it easier to understand and debug. +- Local runs and remote agent runs can now use the same base images, and the + same pre- and post- run hooks. +- Runs are more evenly distributed across Active/Active nodes by eliminating a + redundant queue. +- You can now access previously inaccessible run logs (Sentinel, cost + estimation, and plan-export-worker logs) via Docker logs and any tool that can + interact with it. This includes the `docker logs` command, the Docker API, and + [Terraform Enterprise log forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging). + +In v202302-1, Terraform Enterprise installations using the default worker image (not an alternative worker image) will automatically use the new run pipeline. + +Installations that use an alternative worker image will continue to use the legacy run pipeline when you upgrade to v202302-1. You must migrate your Terraform Enterprise installation to use an agent custom image before adopting v202306-1, which requires rebuilding your alternative worker image as an agent custom image. + +Once you rebuild your image, you must manually switch to the new run pipeline by setting the `run_pipeline_mode = "agent"`. You can revert back to the legacy run pipeline at any time before you adopt v202306-1 by setting `run_pipeline_mode = "legacy"`. The `legacy` option will become unavailable in v202306-1 and later. + +## Check if you use an alternative worker image + +By default, Terraform Enterprise uses the standard image included in a release. You can verify whether your pipeline uses an alternative worker image by reviewing your `settings.json` file or your admin console. + +In the admin console's **Settings** tab, check if **Provide the location of a custom image** is selected. If it is, your pipeline uses the alternative worker image specified in the **Custom image tag** field. + +![The `custom_image_tag` setting in the user interface.](/img/docs/tfe_console-custom_image_tag.png) + +You can also review your `settings.json` file to check if your pipeline uses alternative worker image. If your file includes the `custom_image_tag` field, your pipeline uses the worker image specified. + +## Migrate to a custom agent image + +To migrate to a custom agent image, first review the customizations in +your worker image. Then build your new agent image, add your customizations, and +test the new, customized agent image. + +### Step 1: Evaluate customizations in your current image + +Before making any changes, you must evaluate your current image and familiarize yourself with all of the implemented customizations. + +Consider the following: + +- Which custom tools does your image include? +- Does the image use the initialize and/or finalize hook(s)? +- If yes, what do your initialize and/or finalize script(s) do? + +### Step 2: Build your new custom agent image + +Starting with v202302-1, the Docker container that HCP Terraform and Enterprise uses for Terraform +operations is based on the [`hashicorp/tfc-agent`](https://hub.docker.com/r/hashicorp/tfc-agent) Docker +image. Like the legacy worker image, the agent image supports customizations to perform +custom logic, but there are several implementation differences between +worker images and agent images to consider. + +The following tables describe the differences between the +legacy alternative worker image and the new custom agent image. + +-> **Note:** You must build custom images from `hashicorp/tfc-agent:1.6` or later. + +#### Use an image + +| | Alternative worker image | Custom agent image | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| Building a custom image | [Documentation](/terraform/enterprise/v202301-1/install/interactive/installer#alternative-terraform-worker-image) | [Documentation](/terraform/cloud-docs/agents/agents#optional-configuration-run-an-agent-using-docker) | +| Executing custom scripts | [Documentation](/terraform/enterprise/v202301-1/install/interactive/installer#executing-custom-scripts) | [Documentation](/terraform/cloud-docs/agents/hooks) | +| `settings.json` parameter | Set the `custom_image_tag` field to your custom worker image | Set the `custom_agent_image_tag` field to your custom agent image. | +| Image location | The image must be located on the host. | If Terraform Enterprise cannot find the image on the host, it will try to pull it from the specified location. | + +#### Customize an image + +| | Alternative Worker Image | Custom Agent Image | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Base image | The base image must be `ubuntu:bionic` or an official RHEL7 image (e.g., `registry.access.redhat.com/ubi7/ubi-minimal`). | The base image must be the `hashicorp/tfc-agent`. | +| Image location | The image must exist on the Terraform Enterprise host. You can add it by running `docker pull` from a local registry or any other similar method. | We recommend that the image exist locally, but if it does not, the `tfe-task-worker` Docker driver will pull the image from the specified source. | +| Required software | The image must contain the software packages defined the [requirements](/terraform/enterprise/deploy/replicated/install/interactive/installer#requirements). | N/A | +| Certificates | The `/usr/local/share/ca-certificates` directory must contain all necessary PEM-encoded CA certificates. Each file added to this directory must end with the `.crt` extension. Terraform Enterprise will not automatically add the CA certificates configured in the CA Bundle settings to the image at runtime. | The `/usr/local/share/ca-certificates` directory must contain all necessary PEM-encoded CA certificates. Each file added to this directory must end with the `.crt` extension. Terraform Enterprise will not automatically add the CA certificates configured in the CA Bundle settings to the image at runtime.

This will be similar to the certificate config in this [Dockerfile example](/terraform/enterprise/deploy/replicated/install/interactive/installer#ubuntu). | +| Terraform binary | The image cannot include Terraform. Terraform Enterprise installs Terraform at runtime. | The image cannot include Terraform. Terraform Enterprise installs Terraform at runtime. | +| Rhel 7 | In addition to the packages that `yum` installs, `curl` installs the `envdir` tool Python port because it is a dependency of the Terraform Build Worker service. If the alternative worker image does not include `envdir`, Terraform runs will fail within Terraform Enterprise. | N/A | +| Run before plans and applies | The same [initialize script](/terraform/enterprise/deploy/replicated/install/interactive/installer#initialize-script) runs before a `terraform init` during both plans and applies. | You can have separate [hooks](/terraform/cloud-docs/agents/hooks#supported-hooks) that run before and after plans and applies:
`terraform-pre-plan`
`terraform-pre-apply`. | +| Run after plans and applies | The same [finalize script](/terraform/enterprise/deploy/replicated/install/interactive/installer#finalize-script) runs after `terraform plan` and `terraform apply` complete. | You can have separate [hooks](/terraform/cloud-docs/agents/hooks#supported-hooks) that run before and after plans and applies:
`terraform-post-plan`
`terraform-post-apply` | +| Configuration | Ensure your worker image contains an executable shell script at:
`/usr/local/bin/init_custom_worker.sh`
`/usr/local/bin/finalize_custom_worker.sh` | Store hooks in a hooks directory, and name them according to their purpose. For example:
`~/.tfc-agent/hooks/terraform-pre-plan`
`~/.tfc-agent/hooks/terraform-post-plan`
`~/.tfc-agent/hooks/terraform-pre-apply`
`~/.tfc-agent/hooks/terraform-post-apply` | +| Non-zero exit codes | If the script exits with a non-zero exit code, the Terraform Enterprise run will immediately fail with an error. | If a `terraform apply` does not complete successfully, the hook will still run. If a hook exits with a non-zero exit code, the Terraform run will fail immediately. | +| `stdout`/`stderr` | The build worker logs whether or not a custom script has executed but does not log the script's standard output and standard error. If the custom script exits non-zero, then its standard output and standard error print to the UI logs. | The standard output and standard error from the hook will print alongside the Terraform run output in the HCP Terraform/Enterprise user interface, but not in the UI logs. | +| File locations | You cannot customize the name or location of the script. | The hook name must match one of the [supported hooks](/terraform/cloud-docs/agents/hooks#supported-hooks). You cannot customize or change these names. Because of this, you can only configure one hook of each type for each agent. For example, you could create a pre-plan and pre-apply hook, but you cannot create two pre-plan hooks. | +| Script permissions | The script must have execute permissions. | Each hook must have the execute permission set. | +| Execution timeout | The execution of the script does not have a timeout. It is up to the Terraform Enterprise administrator to ensure scripts execute in a timely fashion. | Each hook has a 60 second timeout. If a hook times out the Terraform run will fail immediately. | +| Execution context | The execution of the script is not sandboxed. The script executes in the same container where `terraform` runs, and both can access the same set of environment variables. | Like with alternative worker images, the execution of the script is not sandboxed. The script executes in the same container where `terraform` runs, and both can access the same set of environment variables. | +| Reading and writing variables | Users can "export" environment variables for subsequent Terraform commands (plan, apply, etc) to use, by writing their environment variable value to a file `/env/FOO` where `FOO` is the name of the environment variable. | Writing to environment variables requires a minimum agent version of [1.9.0](/terraform/cloud-docs/agents/v1.9.x/agents). Instead of directly calling “export”, write to environment variables using “echo”. Terraform parses and sets the environment variable later when other Terraform commands execute. For example, write `echo FOO=bar >> $TFC_AGENT_ENV`, instead of `export FOO=bar`. | +| Running in Docker | Example Dockerfile snippet:
`ADD init_custom_worker.sh /usr/local/bin/init_custom_worker.sh` | When running `tfc-agent` using Docker, you must build a new Docker image containing the hooks. To configure hooks, [follow these instructions](/terraform/cloud-docs/agents/hooks#running-an-agent-with-docker). | +| Execute/running as a binary | Scripts always run in the worker container. To execute, initialize and finalize scripts and all the commands they invoke, ensure your worker image contains an executable shell script at `/usr/local/bin/_custom_worker.sh`. | If you want to run agents outside of containers, you must create your own remote agent pool.

To run hooks as a binary, you need to [change the permissions to the hook scripts](/terraform/cloud-docs/agents/hooks#running-an-agent-as-a-binary). | + +### Step 3: Test your custom agent image + +We strongly recommend that you test your custom agent image before applying it to your production installation of Terraform Enterprise. + +#### Test on Terraform Enterprise v202301 or earlier + +Terraform Enterprise v202301 and earlier use worker images, but you can still test your agent image by configuring a test workspace to use a remote agent. You will need to install your agent on the host of your choice, and configure your workspace to use that agent. Follow the process described [here](/terraform/cloud-docs/agents/agents) for more details. + +#### Test on Terraform Enterprise v202302 or later + +To test in v202302 or later, install a test installation of Terraform Enterprise, define a `custom_agent_image_tag`, and set `run_pipeline_mode = "agent"` in your test installation’s `settings.json`. + +### Step 4: Adopt the new image + +After building and testing the new custom agent image, adopt the new image in your production Terraform Enterprise installation (v202302 or later) by defining a `custom_agent_image_tag`, and setting `run_pipeline_mode = "agent"` in your `settings.json` file. + +## Frequently Asked Questions + +**Q. I currently use an alternative worker image, but I no longer need the customizations. What should I do?** + +**A.** If you want to use the default agent image going forward instead of a customized image, please remove your alternative worker image from use before you upgrade to v202302-1. If you want to remove the alternative worker image after upgrading to v202302-1 or later, set `run_pipeline_mode = "agent"` in your `settings.json` file without specifying a custom agent image. + +**Q. I already use a custom image for my remote agents. Can I re-use that image for my local agent image?** + +**A.** Yes. If your remote agent image accomplishes everything you want, you can specify that image as your custom agent image. + +**Q. I use an alternative worker image, when do I need to complete my migration to a custom agent image?** + +**A.** Terraform Enterprise will stop supporting workers in v202306-1. To maintain your customizations, you must complete your migration to a custom agent image before upgrading to v202306-1 or later. + +**Q. Can I switch back to the legacy run pipeline?** + +**A.** Yes, until v202306-1 you can switch between workers and agents. To switch back to the worker run pipeline, set `run_pipeline_mode = "legacy"` in `settings.json`. We will remove `legacy` mode in v202306-1. + +**Q. I use an alternative worker image to dynamically manage run credentials. What is the best way to accomplish this with a custom agent image?** + +**A.** You can dynamically manage credentials using workspace variables and/or agent hooks. Upcoming enhancements to Terraform Enterprise will make this easier. Please reach out to your HashiCorp account representative for more information. + +**Q. I have a custom workflow on my alternative worker image that does not seem possible on a custom agent image. What should I do?** + +**A.** Please reach out to your HashiCorp account representative for further guidance. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/automated-license-utilization-reporting.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/automated-license-utilization-reporting.mdx new file mode 100644 index 0000000000..8dd4caf7ad --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/automated-license-utilization-reporting.mdx @@ -0,0 +1,113 @@ +--- +page_title: Automated license utilization reporting +description: >- + Learn what data HashiCorp collects to meter Enterprise license utilization. Enable or disable reporting. Review sample payloads and logs. +--- + +@include "replicated-and-fdo/admin/license-utilization-intro.mdx" + +Make sure that your network also allows egress to `https://api.replicated.com` as described in the [network requirements documentation](/terraform/enterprise/deploy/replicated/requirements/network#egress). + +### Upgrade Terraform Enterprise + +Upgrade to Terraform Enterprise [v202305-1](/terraform/enterprise/releases/2023/v202305-1) or later. + +### Check logs + +Automatic license utilization reporting will start sending data within roughly 24 hours. [Check the product logs](/terraform/enterprise/deploy/replicated/monitoring/monitoring#monitoring-a-terraform-enterprise-instance) for records that the data sent successfully. + +```json +{ + "@level": "debug", + "@message": "export finished successfully", + "@module": "tfe-licensing.licensingexporter", + "@timestamp": "2023-05-10T17:48:06.656979Z" +} +``` + +If your installation is air-gapped or your network does not allow the correct egress, logs show the following error: + +```json +{ + "@level": "error", + "@message": "error exporting snapshot", + "@module": "tfe-licensing.census", + "@timestamp": "2023-05-11T01:50:51.662155Z", + "err": "export failed with error POST https://reporting.hashicorp.services giving up after 5 attempt(s): Post \"https://reporting.hashicorp.services\": dial tcp 35.166.5.222:443: i/o timeout" +} +``` + +In this case, reconfigure your network to allow egress and check back in roughly 24 hours. + +## Opt out of license utilization reporting + +If your installation is air-gapped or you want to manually collect and report on the same license utilization metrics, you can opt-out of automated reporting. + +Manually reporting these metrics can be time consuming. Opting out of automated reporting does not mean that you also opt out from sending license utilization metrics. Customers who opt out of automated reporting will still be required to manually collect and send license utilization metrics to HashiCorp. + +If you are considering opting out because you’re worried about the data, we strongly recommend that you review the [example payloads](#example-payloads) before opting out. If you have concerns with any of the automatically-reported data please bring them to your account manager. + +Add the following JSON to the Replicated Application Settings Config (`settings.json`), then check the product logs for a confirmation message. + +```json +{ + "optout_license_reporting": { + "value": 1 + } +} +``` + +If you are on a standalone installation, you can also configure this setting in the [Replicated Admin Console UI](/terraform/enterprise/application-administration/admin-access). + +Now [restart your system](/terraform/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration#restart-terraform-enterprise). + +Check your product logs roughly 24 hours after opting out to make sure that the system isn’t trying to send reports. + +Refer to the [License data reference](/terraform/enterprise/deploy/reference/license-data) for information about the license data Terraform Enterprise reports to HashiCorp. + +## Enable product usage reporting + +Terraform Enterprise reports product usage data to HashiCorp in order to guide you through data insights and improve product value, experience, and quality. You can enable and disable product usage reporting separately from license utilization reporting. + +## Allow outbound HTTPS traffic on port 443 + +Make sure that your network allows egress to `https://api.replicated.com`, as described in the [network requirements documentation](/terraform/enterprise/deploy/replicated/requirements/network#egress). + +Make sure that your network also allows HTTPS egress on port 443 from `https://reporting.hashicorp.services` by allow-listing the following IP addresses: + +- `100.20.70.12` +- `35.166.5.22` +- `23.95.85.111` +- `44.215.244.1` + +### Upgrade Terraform Enterprise + +Upgrade to Terraform Enterprise [v202402-1](/terraform/enterprise/releases/2023/v202402-1) or later. + +### Check logs + +Terraform starts sending data within approximately 24 hours. [Check the product logs](/terraform/enterprise/deploy/replicated/monitoring/monitoring#monitoring-a-terraform-enterprise-instance) for records that the data sent successfully. + +Terraform Enterprise logs report an error when your installation is air-gapped or when your network does not allow the correct egress. + +## Opt out of product usage reporting + +If your installation is air-gapped or you do not want to report product utilization data to HashiCorp, you can opt out of reporting. + +1. Add the following JSON to the Replicated application settings configuration specifying in the `settings.json` file. + + ```json + { + "optout_usage_reporting": { + "value": 1 + } + } + ``` + + If you are on a standalone installation, you can also configure this setting in the Replicated admin console UI. + + +1. Restart your system. +1. Check your product logs roughly 24 hours after opting out to make sure that the system does not send reports. + +@include "replicated-and-fdo/admin/license-example-usage-payload.mdx" \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/index.mdx new file mode 100644 index 0000000000..344cee6b5c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/index.mdx @@ -0,0 +1,20 @@ +--- +page_title: Administration - Legacy Deployment - Terraform Enterprise +description: >- + Learn how to administer the Terraform Enterprise application itself, and the + infrastructure that it runs on. +--- + +# Terraform Enterprise Licenses + +Terraform Enterprise requires a valid license before you can install it. Your HashiCorp account team provides a license after you purchase the product or engage in a trial. This license is required to install a Replicated deployment of Terraform Enterprise. If you are deploying Terraform Enterprise to a non-Replicated runtime, refer to [Configure a license](/terraform/enterprise/deploy/configuration/license) for additional information.. + +Contact your HashiCorp account team for to obtain a license. + +## License + +Refer to the following topics for information about managing your license: + +- [Automated license utilization reporting](/terraform/enterprise/deploy/replicated/administration/license/automated-license-utilization-reporting) + +- [Updating a Terraform Enterprise License](/terraform/enterprise/deploy/replicated/administration/license/update-tfe-license) \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/update-tfe-license.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/update-tfe-license.mdx new file mode 100644 index 0000000000..cd61a73133 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/administration/license/update-tfe-license.mdx @@ -0,0 +1,162 @@ +--- +page_title: >- + Updating Terraform Enterprise License - Application Administration - Terraform + Enterprise +description: >- + Use the Replicated console to manage your Terraform Enterprise license. Learn how to find your license expiration date, update the license online or offline, and troubleshoot license issues. +--- + +# Updating a Terraform Enterprise License + +Terraform Enterprise requires an up-to-date license to maintain normal operations. These licenses have an expiration date, and must be updated once expired. This article provides the guidelines for updating licenses in Terraform Enterprise. + +## Find the License Expiration Date + +You can find the expiration date through either the Replicated console UI or the Replicated command line interface. + +**Note**: [Automated license utilization reporting](/terraform/enterprise/deploy/replicated/administration/license/automated-license-utilization-reporting) automatically sends data to HashiCorp to validate your license entitlements. + +### Replicated Console + +1. Navigate to the Replicated console at `https://<>:8800` and click on the gear icon. + +1. Select the **View License** menu to display the license details, including the expiration date. + +### Replicated Command Line Interface + +1. Connect to the Terraform Enterprise host machine using SSH. + +1. Use the `replicatedctl license inspect` command to inspect the license information. The `ExpirationTime` value in the output indicates the expiration date/time in UTC. + + ```shell + $ replicatedctl license inspect + [ + { + "ID": "670bd320b95245325d80be703330f9b3", + "Assignee": "Test Customer Name", + "LegacyChannelName": "Stable", + "ChannelID": "", + "Channels": [], + "ExpirationTime": "2021-06-30T00:00:00Z", + "ExpirationPolicy": "ignore", + "IsExpired": false, + "IsActivationRequired": false, + "ActivationEmail": "", + "Fields": [ + { + "FieldName": "max_hosts", + "FieldTitle": "Maximum Number of Hosts", + "FieldType": "Integer", + "Value": "9999" + }, + { + "FieldName": "min_hosts", + "FieldTitle": "Minimum Number of Hosts", + "FieldType": "Integer", + "Value": "1" + } + ] + } + ] + ``` + +## Update License - Online Installation Type + +### Automatic Updates + +With the online installation type, you can use the following steps to configure Terraform Enterprise to periodically check for the updated license. + +1. Navigate to the Replicated console at `https://<>:8800` + +1. Click on the gear icon and select the **Console Settings** menu. + +1. Scroll down to the **License Sync** section and select how often Terraform Enterprise should check the license. + +### Manual Updates + +#### Replicated Console + +1. Navigate to the Replicated console at `https://<>:8800`, click the gear icon, and select the **View License** menu. + +1. Click on **Sync License** to start the operation. + +#### Replicated Command Line Interface + +1. Obtain the newly updated license file from HashiCorp and copy it to the Terraform Enterprise host machine. + +1. Connect to the Terraform Enterprise host machine using SSH. + +1. Load the new license. + + ``` + $ replicatedctl license-load < /path/to/license.rli + ``` + +## Update License - Airgap Installation Type + +### Replicated Console + +1. Navigate to the Replicated console at `https://<>:8800`. + +1. Click the gear icon and select the **Console Settings** menu. + +1. Select **Airgapped Settings** and upload the license. + +### Replicated Command Line Interface + +1. Obtain the updated license and airgap package from HashiCorp and copy them to the Terraform Enterprise host. + +1. Connect to the Terraform Enterprise host machine using SSH. + +1. Execute the following command, updating the paths as needed. + + ```shell + $ replicatedctl license-load \ + --airgap-package /path/to/bundle.airgap < /path/to/license.rli + ``` + +## Troubleshooting + +### No error but the license is not updated + +In the Airgap installation, the license update operation may finish without any error but the license detail displayed on the Replicated console or the Replicated command line output is still not updated. This symptom can be related to the incorrect license file being used. In order to further identify the symptom, please follow these steps: + +1. Connect to the Terraform Enterprise host machine using SSH. + +1. Run `docker logs replicated` and look for the warning message below. + + ```plaintext + WARN 2021-02-22T01:40:00+00:00 tasks/app_tasksteps.go:113 Airgap license on disk does not match installed license + ``` + +1. Please contact your assigned Customer Success Manager or [HashiCorp Support](https://www.hashicorp.com/technical-support-services-and-policies) for further assistance. When contacting support, please include the output from running `replicatedctl license inspect` on the Terraform Enterprise host machine. + +### Unable to sync license: Error: Unsuccessful HTTP response + +Terraform can produce this error message for several different issues. + +```plaintext +Unable to sync license: Error: Unsuccessful HTTP response +``` + +- Network communication to the Replicated servers + + Terraform Enterprise requires network communication to the Replicated endpoints, as noted in the [network requirements](/terraform/enterprise/deploy/replicated/requirements/network) guideline. During the license sync operation, the Replicated installer attempts to contact `api.replicated.com` to retrieve the license information. In the online installation type, you might see the above error if the network infrastructure changed after you installed Terraform Enterprise. The specific IP addresses of Replicated services for the Terraform Enterprise are available in [Replicated’s GitHub repository](https://github.com/replicatedhq/ips/blob/master/ip_addresses.json). + +- Customer name on new license does not match existing license + + This may occur with an Airgap installation for a variety of reasons. One example is when a trial license is associated with a different customer name from the subsequent paid license. Please contact [HashiCorp Support](https://www.hashicorp.com/technical-support-services-and-policies) for assistance. In your request, include the output from running`replicatedctl license inspect` on the Terraform Enterprise host machine. + +### Incorrect version of airgap file + +This error indicates that you are using the incorrect version of airgap file against the installed version of Terraform Enterprise. + +```plaintext +installed app release (325b33bf0ad539c994644423128cad5e:502) does not match the airgap package +``` + +The airgap download page displays the versions of Terraform Enterprise and their SHA256 checksum values. Check these against the version of the airgap package in your local environment. + +## Get Support + +If you continue to experience the issues, please contact [HashiCorp Support](https://www.hashicorp.com/technical-support-services-and-policies) for assistance. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/aws.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/aws.mdx new file mode 100644 index 0000000000..cab6f63d07 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/aws.mdx @@ -0,0 +1,433 @@ +--- +page_title: AWS Reference Architecture - Terraform Enterprise +description: |- + This document provides recommended practices and a reference architecture for + HashiCorp Terraform Enterprise implementations on AWS. +--- + +# Terraform Enterprise AWS Reference Architecture + +## Introduction + +This document provides recommended practices and a reference architecture for +HashiCorp Terraform Enterprise implementations on AWS. + +## Implementation Modes + +Terraform Enterprise can be installed and function in different implementation modes with increasing capability and complexity: + +- _Standalone:_ The base architecture with a single application node that supports the standard implementation requirements for the platform. +- _Active/Active:_ This is an extension of _Standalone_ mode that adds multiple active node capability that can expand horizontally to support larger and increasing execution loads. + +Since the architectures of the modes progresses logically, this guide will present the base _Standalone_ mode first and then discuss the differences that alter the implementation into the _Active/Active_ mode. + +## Required Reading + +Prior to making hardware sizing and architectural decisions, read through the +[pre-install checklist](/terraform/enterprise/deploy/replicated/install/pre-install-checklist) +to familiarize yourself with the application components and architecture. +Further, read the [reliability and availability +guidance](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) +as a primer to understanding the recommendations in this reference +architecture. + +## Infrastructure Requirements + +-> **Note:** This reference architecture focuses on the _External Services_ operational mode. + +Depending on the chosen [operational +mode](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operational-mode-decision), +the infrastructure requirements for Terraform Enterprise range from a single AWS EC2 instance +for mounted disk installations to multiple instances connected to RDS and S3 for a +stateless production installation. + +The following table provides high-level server guidelines. Of particular +note is the strong recommendation to avoid non-fixed performance CPUs, +or “Burstable CPU” in AWS terms, such as T-series instances. + +### Terraform Enterprise Server (EC2 via Auto Scaling Group) + +| Type | CPU | Memory | Disk | AWS Instance Types | +| ------- | ------ | --------- | ---- | ------------------ | +| Minimum | 4 core | 16 GB RAM | 50GB | m5.xlarge | +| Scaled | 8 core | 32 GB RAM | 50GB | m5.2xlarge | + +#### Hardware Sizing Considerations + +- The minimum size would be appropriate for most initial production + deployments, or for development/testing environments. + +- The scaled size is for production environments where there is a + consistent high workload in the form of concurrent Terraform runs. + +### PostgreSQL Database (RDS Multi-AZ) + +| Type | CPU | Memory | Storage | AWS Instance Types | +| ------- | ------ | --------- | ------- | ------------------ | +| Minimum | 4 core | 16 GB RAM | 50GB | db.m5d.xlarge | +| Scaled | 8 core | 32 GB RAM | 50GB | db.m5d.2xlarge | + +#### Hardware Sizing Considerations + +- The minimum size would be appropriate for most initial production + deployments, or for development/testing environments. + +- The scaled size is for production environments where there is a + consistent high workload in the form of concurrent Terraform runs. + +### Object Storage (S3) + +An [S3 Standard](https://aws.amazon.com/s3/storage-classes/) bucket must be +specified during the Terraform Enterprise installation for application data to be stored +securely and redundantly away from the EC2 servers running the Terraform Enterprise +application. This S3 bucket must be in the same region as the EC2 and RDS +instances. It is recommended the VPC containing the Terraform Enterprise servers be configured +with a [VPC endpoint for +S3](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints.html). +Within the Terraform Enterprise application, Vault is used to encrypt all application data stored in the S3 bucket. This +allows for further [server-side +encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html) +by S3 if required by your security policy. + +-> **Note:** Terraform Enterprise has routine jobs that delete expired objects from S3 storage and operations that destroy database records and the associated storage objects. We recommend enabling S3 Versioning so that you will have regular snapshots that you can use to restore your database if necessary. + +### Other Considerations + +#### Additional AWS Resources + +In order to successfully provision this reference architecture you must +also be permitted to create the following AWS resources: + +- VPC +- Subnet +- Route Table +- Route Table Association +- Security Group +- Load Balancer (Application, Network, or Classic Load Balancer) +- Launch Configuration +- Auto Scaling Group +- Target Group (if using Application or Network Load Balancer) +- CloudWatch Alarm +- IAM Instance Profile +- IAM Role +- IAM Role Policy +- Route 53 (optional) + +#### Network + +To deploy Terraform Enterprise in AWS you will need to create new or use existing +networking infrastructure. The below infrastructure diagram highlights +some of the key components (VPC, subnets, DB subnet group) and you will +also have security group, routing table and gateway requirements. These +elements are likely to be very unique to your environment and not +something this Reference Architecture can specify in detail. An [example Terraform +configuration](https://github.com/hashicorp/private-terraform-enterprise/blob/master/examples/aws/network/main.tf) +is provided to demonstrate how these resources can be provisioned and +how they interrelate. + +#### DNS + +DNS can be configured external to AWS or using [Route 53](https://aws.amazon.com/route53/). The +fully qualified domain name should resolve to the Load Balancer (if using one) or the Terraform Enterprise instance using a +CNAME if using external DNS or an [alias +record set](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html) +if using Route 53. Creating the required DNS entry is outside the scope +of this guide. + +Another approach would be to use an external registrar or DNS server to point to a Route 53 CNAME record using +a canonical, but not necessarily public, domain name, which then forwards to the ALIAS record for the ELB. This +pattern is required if using Route 53 Health Checks and failover pairs to automatically fail over to the standby +instance. This is documented further below. + +#### SSL/TLS Certificates and Load Balancers + +An SSL/TLS certificate signed by a public or private CA is required for secure communication between +clients, VCS systems, and the Terraform Enterprise application server. The certificate can be specified during the +UI-based installation or in a configuration file used for an unattended installation. + +If a Classic or Application Load Balancer is used, SSL/TLS will be terminated on the load balancer. +In this configuration, the Terraform Enterprise instances should still be configured to listen +for incoming SSL/TLS connections. If a Network Load Balancer is used, SSL/TLS may be terminated at the load balancer +or on the Terraform Enterprise instance. + +HashiCorp does not recommend the use of self-signed certificates on the Terraform Enterprise instance unless you use a +load balancer and place a public certificate (such as an AWS Certificate Manager certificate) +on the load balancer. + +If you want to use a Network Load Balancer (NLB) with Terraform Enterprise, use either an internet-facing NLB or an internal NLB that targets by IP. +An internal NLB that targets by instance ID cannot be used with Terraform Enterprise since NLBs configured in this way do not support loopbacks. +Amazon provides [load balancer troubleshooting](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-troubleshooting.html) +information for Network Load Balancers. + +### Infrastructure Diagram - Standalone + +![aws-sa-infrastructure-diagram](/img/docs/RA-TFE-SA-AWS-SingleRegion.png) + +### Application Layer + +The Application Layer is composed of an Auto Scaling Group and a Launch Configuration +providing an auto-recovery mechanism in the event of an instance or Availability Zone failure. + +### Storage Layer + +The Storage Layer is composed of multiple service endpoints (RDS, S3) all +configured with or benefiting from inherent resiliency +provided by AWS. + +#### Additional Information + +- [RDS Multi-AZ deployments](https://aws.amazon.com/rds/details/multi-az/) + +- [S3 Standard storage class](https://aws.amazon.com/s3/storage-classes/) + +## Infrastructure Provisioning + +The recommended way to deploy Terraform Enterprise is through use of a Terraform configuration +that defines the required resources, their references to other resources, and associated +dependencies. + +## Normal Operation + +### Component Interaction + +The Load Balancer routes all traffic to the Terraform Enterprise instance, which is managed by +an Auto Scaling Group with maximum and minimum instance counts set to one. + +The Terraform Enterprise application is connected to the PostgreSQL database via the RDS +Multi-AZ endpoint and all database requests are routed via the RDS +Multi-AZ endpoint to the _RDS-main_ database instance. + +The Terraform Enterprise application is connected to object storage via the S3 endpoint +for the defined bucket and all object storage requests are routed to the +highly available infrastructure supporting S3. + +### Monitoring + +There is not currently a full monitoring guide for Terraform Enterprise. The following pages include information relevant to monitoring: + +- [Log Forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging) +- [Diagnostics](/terraform/enterprise//deploy/troubleshoot) +- [Reliability and Availability](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) + +### Upgrades + +See [the Upgrades section](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) of the documentation. + +## High Availability - Failure Scenarios + +AWS provides availability and reliability recommendations in the [Well-Architected +framework](https://aws.amazon.com/architecture/well-architected/). +Working in accordance with those recommendations, the Terraform Enterprise Reference +Architecture is designed to handle different failure scenarios with +different probabilities. As the architecture evolves it will provide a +higher level of service continuity. + +### Terraform Enterprise Server + +By utilizing an Auto Scaling Group, a Terraform Enterprise instance can automatically recover +in the event of any outage except for the loss of an entire region. + +In the event of a Terraform Enterprise instance failing in a way that AWS can +observe, the health checks on the Auto Scaling Group trigger, causing +a replacement instance to be launched. Once launched, +it reinitializes the software, and on completion, processing on this EC2 instance will +resume as normal. + +With _External Services_ (PostgreSQL Database, Object Storage) in use, +there is still some application configuration data present on the Terraform Enterprise server +such as installation type, database connection settings, hostname. This data +rarely changes. If the configuration on Terraform Enterprise changes you should update the +Launch Configuration to include the updates so that any newly +launched EC2 instance uses them. + +### Availability Zone Failure + +In the event of the Availability Zone hosting the main instances (EC2 +and RDS) failing, the Auto Scaling Group for the EC2 instance will automatically +begin booting a new one in an operational AZ. + +- Multi-AZ RDS automatically fails over to the RDS Standby Replica + (_RDS-standby_). The [AWS documentation provides more + detail](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html) + on the exact behavior and expected impact. + +- S3 is resilient to Availability Zone failure based on its architecture. + +See below for more detail on how each component handles Availability Zone failure. + +### PostgreSQL Database + +Using RDS Multi-AZ as an external database service leverages the highly +available infrastructure provided by AWS. From the AWS website: + +> _In a Multi-AZ deployment, Amazon RDS automatically provisions and +> maintains a synchronous standby replica in a different Availability +> Zone. In the event of a planned or unplanned outage of your DB +> instance, Amazon RDS automatically switches to a standby replica in +> another Availability Zone. ([source](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html))_ + +### Object Storage + +Using S3 as an external object store leverages the highly available +infrastructure provided by AWS. S3 buckets are replicated to all +Availability Zones within the region selected during bucket creation. +From the AWS website: + +> _Amazon S3 runs on the world’s largest global cloud infrastructure, +> and was built from the ground up to deliver a customer promise of +> 99.999999999% of durability. Data is automatically distributed across +> a minimum of three physical facilities that are geographically +> separated within an AWS Region. ([source](https://aws.amazon.com/s3/))_ + +## Disaster Recovery - Failure Scenarios + +AWS provides availability and reliability recommendations in the [Well-Architected +framework](https://aws.amazon.com/architecture/well-architected/). Working in accordance with those +recommendations the Terraform Enterprise Reference Architecture is designed to handle +different failure scenarios that have different probabilities. As the +architecture evolves it will provide a higher level of service +continuity. + +### Data Corruption + +The Terraform Enterprise application architecture relies on multiple service endpoints +(RDS, S3) all providing their own backup and recovery +functionality to support a low MTTR in the event of data corruption. + +### PostgreSQL Database + +Backup and recovery of PostgreSQL is managed by AWS and configured +through the AWS management console on CLI. More details of RDS for +PostgreSQL features are available [here](https://aws.amazon.com/rds/postgresql/) +and summarised below: + +> _Automated Backups – The automated backup feature of Amazon RDS is +> turned on by default and enables point-in-time recovery for your DB +> Instance. Amazon RDS will backup your database and transaction logs +> and store both for a user-specified retention period._ +> +> _DB Snapshots – DB Snapshots are user-initiated backups of your DB +> Instance. These full database backups will be stored by Amazon RDS +> until you explicitly delete them._ + +### Object Storage + +There is no automatic backup/snapshot of S3 by AWS, so it is recommended +to script a bucket copy process from the bucket used by the Terraform Enterprise +application to a “backup bucket” in S3 that runs at regular intervals. +The [Amazon S3 Standard-Infrequent +Access](https://aws.amazon.com/s3/storage-classes/) storage class +is identified as a solution targeted more for DR backups than S3 +Standard. From the AWS website: + +> _Amazon S3 Standard-Infrequent Access (S3 Standard-IA) is an Amazon S3 +> storage class for data that is accessed less frequently, but requires +> rapid access when needed. S3 Standard-IA offers the high durability, +> high throughput, and low latency of S3 Standard, with a low per GB +> storage price and per GB retrieval fee. This combination of low cost +> and high performance make S3 Standard-IA ideal for long-term storage, +> backups, and as a data store for disaster recovery. ([source](https://aws.amazon.com/s3/storage-classes/))_ + +## Multi-Region Deployment to Address Region Failure + +Terraform Enterprise is currently architected to provide high availability within a +single AWS Region. Using multiple AWS Regions will give you greater +control over your recovery time in the event of a hard dependency +failure on a regional AWS service. In this section, implementation patterns to support this are discussed. + +We recommend provisioning an identical infrastructure in a secondary AWS +Region. Depending on recovery time objectives and tolerances for +additional cost to support AWS Region failure, the infrastructure can be +running (Warm Standby) or stopped (Cold Standby). Please note that with _Standalone_ implementation mode, only one Terraform Enterprise instance can be running against the same database. + +This deployment acts to minimize the Mean Time To Recovery (MTTR) in the event of a regional failure, avoiding the need to replicate and stand up the data plane infrastructure during an outage. If the primary AWS Region hosting the Terraform Enterprise application fails, you will need to perform some configuration before traffic is directed to the secondary AWS Region: + +- [RDS cross-region read replicas](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html) can be used in a warm standby architecture or [RDS database backups](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_CommonTasks.BackupRestore.html) can be used in a cold standby architecture. + +- [S3 cross-region replication](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html) must be configured so the object storage component of the Storage Layer is available in the secondary AWS Region. + +- DNS must be redirected to the Load Balancer acting as the entry point for the infrastructure deployed in the secondary AWS Region. + +## Active/Active Implementation Mode + +### Overview + +As stated previously, the _Active/Active_ implementation mode is an extension of the _Standalone_ implementation mode that increases the scalability and load capacity of the Terraform Enterprise platform. The same application runs on multiple Terraform Enterprise instances utilizing the same external services in a shared model. The primary architectural and implementation differences for _Active/Active_ are: + +- It can only be run in the _External Services_ mode. +- The additional nodes are active and processing work at all times. +- In addition to the existing external services, there is a memory cache which is currently implemented with cloud native implementations of Redis. This is used for the processing queue for the application and has been moved from the individual instance to be a shared resource that manages distribution of work. +- There are additional configuration parameters to manage the operation of the node cluster and the memory cache. + +The following sections will provide further detail on the infrastructure and implementation differences. + +### Migration to Active/Active + +If you are considering a migration from a _Standalone_ implementation to _Active/Active_, it is straightforward and there is guidance available to assist with that effort. However, you should first make a determination if the move is necessary. The _Standalone_ mode is capable of handling significant load and the first paths to supporting higher load can be simply increasing the compute power in the existing implementation. A discussion with your HashiCorp representatives may be warranted. + +Also note that if your existing architecture does not already depict what is shown and discussed above, you will likely need to make adjustments to bring it into alignment. This could be either before or during the migration. Certain tenets of the reference architecture described here are highly recommended and potentially necessary to support _Active/Active_ mode such as load balancers and scaling groups. + +### Infrastructure Diagram - Active/Active + +![aws-aa-infrastructure-diagram](/img/docs/RA-TFE-AA-AWS-SingleRegion.png) + +The above diagram shows the infrastructure components of an _Active/Active_ implementation at a high-level. + +### Infrastructure Requirements + +#### Active Nodes + +The diagram depicts two active nodes to be concise. Additional nodes can be added by altering your configuration to launch another instance that points to the same shared external services. The number and sizing of nodes should be based on load requirements and redundancy needs. Nodes should be deployed in alternate zones to accommodate zone failure. + +The cluster is comprised of essentially independent nodes in a SaaS type model. There are no concerns of leader election or minimal or optimum node counts. When a new node enters the cluster it simply starts taking new work from the load balancer and from the memory cache queue and thus spreading the load horizontally. + +#### Memory Cache + +The AWS implementation of the memory cache is handled by [Amazon ElastiCache](https://aws.amazon.com/elasticache/), specifically using the [ElastiCache for Redis](https://aws.amazon.com/elasticache/redis/) service. [Getting Started with Amazon ElastiCache for Redis](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/GettingStarted.html) provides a high level walk-through of implementing the service. + +[Determine Your Requirements](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/cluster-create-determine-requirements.html) provides details regarding the implementation options for the memory cache. +For Terraform Enterprise, we recommend a Redis (cluster mode disabled) cluster and enabling Multi-AZ with Automated Failover to improve fault tolerance and reduce downtime. Enabling Multi-AZ on your replication group minimizes the impact of a primary node failure by automatically failing over ElastiCache to a replica. For more information, refer to [Minimizing downtime in ElastiCache for Redis with Multi-AZ](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/AutoFailover.html). + +In addition to enabling Multi-AZ with Redis Replication Groups, ensure the memory cache replica nodes are located across availability zones as described in [Mitigating Failures](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/FaultTolerance.html). There should be a replica node in every AZ that has a Terraform Enterprise compute instance deployed for the cluster. While testing environments may use a single node, production environments should prioritize high availability with replication. For specifics on how Amazon ElastiCache for Redis handles replication, visit [Understanding Redis replication](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/Replication.Redis.Groups.html). + +When sizing for Amazon ElasticCache, choose from the available `cache.x.x` EC2 instance sizes for your cluster. Start with a smaller size taking into consideration the anticipated load, like `cache.m5.large` and adjust based on the actual demand. You can find help in the [Choosing Your Node Size](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/nodes-select-size.html#CacheNodes.SelectSize) guide. + +Security is a priority in Amazon ElasticCache, as Redis instances are protected by private IPs and access is restricted to the account owning the cluster. Use Security Groups to limit access by port to the Redis cluster. For more information, consult the [Access Authorization](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/GettingStarted.AuthorizeAccess.html) guide. + +For Redis version compatibility requirements, see the Terraform Enterprise [operational mode requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements#active-active-mode) + +Additional information: + +- Terraform Enterprise currently does not support or require Redis (cluster mode enabled) clusters, as the compute instances are architected to provide high availability within a single region. See [Multi-Region Implementation to Address Region Failure](#multi-region-implementation-to-address-region-failure) for more details. +- Local Zone is an option in Amazon ElasticCache that brings the memory cache geographically closer to users. However, we do not recommend this feature for Terraform Enterprise because the memory cache nodes only need to be close to Terraform Enterprise compute nodes, and it also doesn't support Multi-AZ. +- It is worth noting that [Redis Append Only Files (AOF) for transaction logs](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/FaultTolerance.html#FaultTolerance.Redis.Cluster.AOF) is considered an alternative to Replication Groups for mitigating cluster failures, however we do not recommend this approach due to its shortcomings. + +### Normal Operation + +#### Component Interaction + +The Load Balancer routes all traffic to the Terraform Enterprise instance, which is managed by +an Auto Scaling Group. This is a standard round-robin distribution for now, with no accounting for current load on the nodes. The instance counts on the Auto Scaling Group control the number of nodes in operation and can be used to increase or decrease the number of active nodes. + +_Active/Active_ Terraform Enterprise is not currently architected to support dynamic scaling based on load or other factors. The maximum and minimum instance counts on the Auto Scaling Group should be set to the same value. Adding a node can be done at will by setting these values. However, removing a node requires that the node be allowed to finish active work and stop accepting new work before being terminated. The operational documentation has the details on how to "drain" a node. + +#### Replicated Console + +The Replicated Console that allows access to certain information and realtime configuration for _Standalone_ is not available in _Active/Active_. This functionality, including generating support bundles, has been replaced with CLI commands to be executed on the nodes. The operational documentation has the details on how to utilize these commands. + +#### Upgrades + +Upgrading the Terraform Enterprise version still follows a similar pattern as with _Standalone_. However, there is not an online option with the Replicated Console. It is possible to upgrade a minor release with CLI commands in a rolling fashion. A "required" release or any change that potentially affects the shared external services will need to be done with a short outage. This involves scaling down to a single node, replacing that node, and then scaling back out. The operational documentation has the details on how these processes can operate. + +### Failure Scenarios + +#### Memory Cache + +As mentioned, the Amazon ElasticCache service in Multi-AZ mode provides automatic replication and failover. In the event of a larger failure or any normal maintenance with proper draining, the memory cache will not be required to be restored. If it is damaged it can be re-paved, and if not it can be left to continue operation. + +### Multi-Region Implementation to Address Region Failure + +Similar to _Standalone_, _Active/Active_ Terraform Enterprise is currently architected to provide high availability within a +single region. You cannot deploy additional nodes associated to the primary cluster in different regions. It is possible to deploy to multiple regions to give you greater +control over your recovery time in the event of a hard dependency +failure on a regional service. An identical infrastructure will still need to be instantiated separately with a failover scenario resulting in control of processing being transferred to the second implementation, as described in the earlier section on this topic. In addition, this identical infrastructure will require its own Memory Cache external service instance. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/azure.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/azure.mdx new file mode 100644 index 0000000000..ac99d1c521 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/azure.mdx @@ -0,0 +1,406 @@ +--- +page_title: Azure Reference Architecture - Terraform Enterprise +description: |- + This document provides recommended practices and a reference + architecture for HashiCorp Terraform Enterprise + implementations on Azure. +--- + +# Terraform Enterprise Azure Reference Architecture + +## Introduction + +This document provides recommended practices and a reference +architecture for HashiCorp Terraform Enterprise +implementations on Azure. + +## Implementation Modes + +Terraform Enterprise can be installed and function in different implementation modes with increasing capability and complexity: + +- _Standalone:_ The base architecture with a single application node that supports the standard implementation requirements for the platform. +- _Active/Active:_ This is an extension of _Standalone_ mode that adds multiple active node capability that can expand horizontally to support larger and increasing execution loads. + +Since the architectures of the modes progresses logically, this guide will present the base _Standalone_ mode first and then discuss the differences that alter the implementation into the _Active/Active_ mode. + +## Required Reading + +Prior to making hardware sizing and architectural decisions, read through the +[pre-install checklist](/terraform/enterprise/deploy/replicated/install/pre-install-checklist) +to familiarize yourself with the application components and architecture. +Further, read the [reliability and availability +guidance](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) +as a primer to understanding the recommendations in this reference +architecture. + +## Infrastructure Requirements + +-> **Note:** This reference architecture focuses on the _External Services_ operational mode. + +Requirements depend on the chosen [operational +mode](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#opearational-mode-decision). For example, +an installation on Mounted Disk mode may require a single Azure VM instance, +whereas a stateless production installation may require multiple instances +connected to [Azure Database for +PostgreSQL](https://azure.microsoft.com/en-us/services/postgresql/) and [Azure +Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) for a +stateless production installation. + +The following table provides high-level server recommendations and is meant as +a guideline. Of particular note is the strong recommendation to avoid non-fixed +performance CPUs, or “Burstable CPU” in Azure terms, such as B-series +instances. + +### Terraform Enterprise Servers (Azure VMs) + +| Type | CPU | Memory | Disk | Azure VM Sizes | +| ------- | ------ | --------- | ---- | -------------- | +| Minimum | 4 core | 16 GB RAM | 50GB | Standard_D4_v4 | +| Scaled | 8 core | 32 GB RAM | 50GB | Standard_D8_v4 | + +#### Hardware Sizing Considerations + +- The default osDisk size for most Linux images on Azure is 30GB. When + increasing the size of the osDisk partition, there may be additional + steps required to fully utilize the disk space, such as using a tool + like `fdisk`. This process is documented in the Azure knowledge base + article ["How to: Resize Linux osDisk partition on Azure"](https://blogs.msdn.microsoft.com/linuxonazure/2017/04/03/how-to-resize-linux-osdisk-partition-on-azure/). + +- The minimum size would be appropriate for most initial production + deployments or for development/testing environments. + +- The scaled size is for production environments where there is a + consistently high workload in the form of concurrent Terraform runs. + +### PostgreSQL Database (Azure Database for PostgreSQL) + +| Type | CPU | Memory | Storage | Azure DB Sizes | +| ------- | ------ | --------- | ------- | -------------- | +| Minimum | 4 core | 8 GB RAM | 50GB | GP_Gen5_4 | +| Scaled | 8 core | 16 GB RAM | 50GB | GP_Gen5_8 | + +#### Hardware Sizing Considerations + +- The minimum size would be appropriate for most initial production + deployments or for development/testing environments. +- The scaled size is for production environments where there is + a consistent high workload in the form of concurrent Terraform + runs. + - Be aware that a 4 vCPU database has a maximum capacity of 1Tb. For organizations which require long-term logging for audit, larger databases may be required. The 8 vCPU database has a maximum of 1.5Tb. + +### Object Storage (Azure Blob Storage) + +An Azure Blob Storage +[container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction#containers) +must be specified during the Terraform Enterprise installation for application data to +be stored securely and redundantly away from the Azure VMs running the +Terraform Enterprise application. This Azure Blob Storage container must be in the same +region as the VMs and Azure Database for PostgreSQL instance. + +We recommend that the virtual network containing the Terraform Enterprise servers be configured with a +[Virtual Network (VNet) service +endpoint](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-service-endpoints-overview) +for Azure Storage. Vault is used to encrypt all application data stored +in the Azure Blob Storage container. This allows for further +[server-side +encryption](https://docs.microsoft.com/en-us/azure/storage/common/storage-service-encryption) +by Azure Blob Storage if required by your security policy. + +For increased durability in a single-region deployment, we recommend using zone-redundant storage (ZRS) which synchronously writes across three Azure availability zones in the region. For a multi-region deployment, use geo-zone-redundant storage (GZRS) for added region redundancy. + +### Other Considerations + +#### Additional Azure Resources + +In order to successfully provision this reference architecture you must +also be permitted to create the following Azure resources: + +- [Resource Group(s)](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview#resource-groups) + +- [Load Balancer](https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview) + +- [Virtual Network](https://azure.microsoft.com/en-us/services/virtual-network/) + +- [Subnet](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-manage-subnet) + +- [Public IP](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-ip-addresses-overview-arm#public-ip-addresses) + +- [Managed Disk](https://azure.microsoft.com/en-us/services/managed-disks/) + +- [Network Interface](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-network-interface) + +#### Network + +To deploy Terraform Enterprise in Azure you will need to create new or use existing +networking infrastructure. The infrastructure diagram highlights some of +the key components. These elements are likely to be very unique to your +environment and not something this Reference Architecture can specify in +detail. + +#### Load Balancer + +There are a few options available: + +- Azure Public Load Balancer: This is a layer-4 Load Balancer and offers the simplest solution Azure has to offer. In this mode you must do TLS pass-through and can not use a Web Application Firewall (WAF), although this is often mitigated with other firewall appliances that sit in front of the Load Balancer + +- Azure Public Application Gateway: this is a layer-7 Load Balancer, offers more features and is more reliable than the public Load Balancer, but is more complex. In this mode, you can do TLS termination, however, you must also serve the same certificate on the backend instances essentially creating a pass-through scenario. You can use a Web Application Firewall (WAF) in this configuration. Application Gateway can utilize version 2 of the PaaS in Azure, but private IP addressing is not possible with this option + +- Azure Private Application Gateway: this is a layer-7 Load Balancer, offers more features and is more reliable than the public Load Balancer, but is more complex. In this mode you can do TLS termination, however, you must also serve the same certificate on the backend instances, essentially creating a pass-through scenario, and you must also upload a private CA bundle to the Application Gateway. In the Private configuration, Application Gateway can utilize **ONLY** version 1 of the PaaS in Azure, but can use private IP addresses. + +#### DNS + +DNS can be configured outside of Azure or using +[Azure +DNS](https://azure.microsoft.com/en-gb/services/dns/). The fully +qualified domain name should resolve to the Load Balancer. Creating the +required DNS entry is outside the scope of this guide. + +#### SSL/TLS + +An SSL/TLS certificate is required for secure communication between +clients and the Terraform Enterprise application server. The certificate can be +specified during the UI-based installation or the path to the +certificate codified during an unattended installation. + +### Infrastructure Diagram - Standalone + +![azure-infrastructure-diagram](/img/docs/RA-TFE-SA-Azure-SingleRegion.png) + +The above diagram show the infrastructure components at a high-level. + +-> **Note:** The diagram shows an Azure load balancer but for private IP usage in a hybrid model, use an Azure Application Gateway v1. Also note that the VM Scale Set would be declared as multi-zone in order to benefit from cross-availability zone redundancy. + +### Application Layer + +For a single-region deployment, the Application Layer is composed of a multi-AZ VM scale set of one Terraform Enterprise server (Azure VM) running in different availability zones in a single subnet. Were the VM to fail due to unplanned events such as hardware or software faults or a network issue such as an availability zone outage, the scale set would recreate the instance in the other zone. + +-> **Note:** As Microsoft currently do not support multi-region global load balancing using private IP addressing, a multi-region deployment is only possible using public IP addressing. See [this document](https://docs.microsoft.com/en-us/azure/architecture/guide/technology-choices/load-balancing-overview#decision-tree-for-load-balancing-in-azure) for more information. + +### Storage Layer + +The Storage Layer is composed of multiple service endpoints (Azure Database for PostgreSQL and +Azure Blob Storage) all configured with or benefitting from +inherent resiliency provided by Azure. + +#### Additional Information + +- [Azure Database for PostgreSQL deployments](https://docs.microsoft.com/en-us/azure/postgresql/concepts-business-continuity) + +- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) + +## Infrastructure Provisioning + +The recommended way to deploy Terraform Enterprise is through use of a Terraform +configuration that defines the required resources, their references to +other resources, and associated dependencies. + +## Normal Operation + +### Component Interaction + +The Load Balancer routes all traffic to the active Terraform Enterprise instance, which +handles all requests to the Terraform Enterprise application. + +The Terraform Enterprise application is connected to the PostgreSQL database via the +Azure provided database server name endpoint. All database requests are +routed to the highly available infrastructure supporting Azure Database for PostgreSQL. + +The Terraform Enterprise application is connected to object storage via the Azure Blob +Storage endpoint for the defined container. All object storage requests +are routed to the highly available infrastructure supporting Azure Storage. + +### Monitoring + +There is not currently a full monitoring guide for Terraform Enterprise. The following pages include information relevant to monitoring: + +- [Log Forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging) +- [Diagnostics](/terraform/enterprise//deploy/troubleshoot) +- [Reliability and Availability](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) + +### Upgrades + +See [the Upgrades section](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) of the documentation. + +## High Availability - Failure Scenarios + +Azure provides availability and reliability recommendations on [Azure reliability](https://azure.microsoft.com/en-us/features/reliability/). Working in accordance with those recommendations, the Terraform Enterprise Reference Architecture is designed to handle different failure +scenarios that have different probabilities. As the architecture evolves it will provide a +higher level of service continuity. + +### Terraform Enterprise Server + +By utilizing an VM Scale Set, a Terraform Enterprise instance can automatically recover +in the event of any outage except for the loss of an entire region. + +In the event of a Terraform Enterprise instance failing in a way that Azure can observe, the health checks on the VM Scale Set trigger, causing a replacement instance to be launched. Once launched, it reinitializes the software, and on completion, processing on this Azure VM will resume as normal. + +With _External Services_ (PostgreSQL Database, Object Storage) in use, +there is still some application configuration data present on the Terraform Enterprise server +such as installation type, database connection settings, hostname. This data +rarely changes. If the configuration on Terraform Enterprise changes you should include this updated scale set configuration so that any newly launched instance uses this it. + +### PostgreSQL Database + +The Azure Database for PostgreSQL service provides a guaranteed high +level of availability. The financially backed service level agreement +(SLA) is 99.99% upon general availability. There is virtually no +application down time when using this service. More information on Azure +Database for PostgreSQL service redundancy is available in the +[Azure +documentation](https://docs.microsoft.com/en-us/azure/postgresql/concepts-high-availability). + +### Object Storage + +Using Azure Blob Storage as an external object store leverages the +highly available infrastructure provided by Azure. More information on +Azure Storage redundancy is available in the +[Azure +documentation](https://docs.microsoft.com/en-us/azure/storage/common/storage-redundancy). + +## Disaster Recovery - Failure Scenarios + +Azure provides availability and reliability recommendations on [Azure reliability](https://azure.microsoft.com/en-us/features/reliability/). Working in accordance with those recommendations the Terraform Enterprise Reference Architecture is designed to handle different failure +scenarios that have different probabilities. The ability to provide better +service continuity will improve as the architecture evolves. + +### Data Corruption + +The Terraform Enterprise application architecture relies on multiple service endpoints +(Azure DB and Azure Storage) all providing their own backup and +recovery functionality to support a low MTTR in the event of data +corruption. + +### PostgreSQL Database + +Backup and recovery of PostgreSQL is managed by Azure and configured +through the Azure portal or CLI. More details of Azure DB for PostgreSQL +features are available +[here](https://docs.microsoft.com/en-us/azure/postgresql/concepts-backup) +and summarised below: + +> _Automated Backups – Azure Database for PostgreSQL automatically +> creates server backups and stores them in user configured locally +> redundant or geo-redundant storage._ +> +> _Backup redundancy – Azure Database for PostgreSQL provides the +> flexibility to choose between locally redundant or geo-redundant +> backup storage._ + +### Object Storage + +There is no automatic backup/snapshot of Azure Blob Storage by Azure, so it +is recommended to script a container copy process from the container +used by the Terraform Enterprise application to a “backup container” in Azure Blob Storage +that runs at regular intervals. It is important the copy process is not +so frequent that data corruption in the source content is copied to the +backup before it is identified. + +## Multi-Region Deployment to Address Region Failure + +Terraform Enterprise is currently architected to provide high availability within a +single Azure Region only. It is possible to deploy to multiple Azure Regions to give you greater +control over your recovery time in the event of a hard dependency +failure on a regional Azure service. In this section, implementation patterns to support this are discussed. + +An identical infrastructure should be provisioned in a secondary Azure +Region. Depending on recovery time objectives and tolerances for +additional cost to support Azure Region failure, the infrastructure can be +running (Warm Standby) or stopped (Cold Standby). In the event of the primary Azure Region hosting the Terraform Enterprise +application failing, the secondary Azure Region will require some +configuration before traffic is directed to it along with some global +services such as DNS. + +- [Azure Database for PostgreSQL's + geo-restore + feature](https://docs.microsoft.com/en-us/azure/postgresql/concepts-business-continuity) + provides the ability to recover the database backup to the + secondary Azure Region. + +- [Geo-zone-redundant storage (GZRS) for Azure + Storage](https://docs.microsoft.com/en-us/azure/storage/common/storage-redundancy#redundancy-in-a-secondary-region) + must be configured so the object storage component of the Storage + Layer is available in the secondary Azure Region. + +- DNS must be redirected to the Load Balancer acting as the entry + point for the infrastructure deployed in the secondary Azure + Region. + +## Active/Active Implementation Mode + +### Overview + +As stated previously, the _Active/Active_ implementation mode is an extension of the _Standalone_ implementation mode that increases the scalability and load capacity of the Terraform Enterprise platform. The same application runs on multiple Terraform Enterprise instances utilizing the same external services in a shared model. The primary architectural and implementation differences for _Active/Active_ are: + +- It can only be run in the _External Services_ mode. +- The additional nodes are active and processing work at all times. +- In an addition to the existing external services, there is a memory cache which is currently implemented with cloud native implementations of Redis. This is used for the processing queue for the application and has been moved from the individual instance to be a shared resource that manages distribution of work. +- There are additional configuration parameters to manage the operation of the node cluster and the memory cache. + +The following sections will provide further detail on the infrastructure and implementation differences. + +### Migration to Active/Active + +If you are considering a migration from a _Standalone_ implementation to _Active/Active_, it is straightforward and there is guidance available to assist with that effort. However, you should first make a determination if the move is necessary. The _Standalone_ mode is capable of handling significant load and the first paths to supporting higher load can be simply increasing the compute power in the existing implementation. A discussion with your HashiCorp representatives may be warranted. + +Also note that if your existing architecture does not already depict what is shown and discussed above, you will likely need to make adjustments to bring it into alignment. This could be either before or during the migration. Certain tenets of the reference architecture described here are highly recommended and potentially necessary to support _Active/Active_ mode such as load balancers and scaling groups. + +### Infrastructure Diagram - Active/Active + +![aws-aa-infrastructure-diagram](/img/docs/RA-TFE-AA-Azure-SingleRegion.png) + +The above diagram shows the infrastructure components of an _Active/Active_ implementation at a high-level. + +### Infrastructure Requirements + +#### Active Nodes + +The diagram depicts two active nodes to be concise. Additional nodes can be added by altering your configuration to launch another instance that points to the same shared external services. The number and sizing of nodes should be based on load requirements and redundancy needs. Nodes should be deployed in alternate zones to accommodate zone failure. + +The cluster is comprised of essentially independent nodes in a SaaS type model. There are no concerns of leader election or minimal or optimum node counts. When a new node enters the cluster it simply starts taking new work from the load balancer and from the memory cache queue and thus spreading the load horizontally. + +#### Memory Cache + +The Azure implementation of the memory cache is handled by [Azure Cache for Redis](https://azure.microsoft.com/en-us/services/cache/). Specifically documented in [Azure Cache for Redis Documentation](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/). + +[About Azure Cache for Redis](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/cache-overview) provides a high level walk-through of implementing the memory cache with a description of some of the implementation options. Primary differentiators are set by tiers from "Basic" to "Enterprise Flash" described [this section](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/cache-overview#service-tiers) including a chart by feature sets . The primary differences are sizing/capacity and how far high availability and fault tolerance might extend. Note that only the Premium and Enterprise tiers provide persistence and encryption and true zone redundancy. The enterprise tiers involve actually acquiring Redis Enterprise licensees through the Azure Marketplace which is an option if that level of direct vendor support is desired/required. You can start at a lower tier and migrate upwards, however, migrating downwards is not supported, other than re-creating the memory cache. + +You should start by selecting the tier level appropriate to the environment you are deploying. A lower testing or sandbox environment could use a Basic or Standard tier. However, a production level environment should always be configured with Premium or Enterprise tiers to benefit from the HA features that coincide with the other external services in the Terraform Enterprise platform. Additional considerations described in [Best practices](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/cache-best-practices) can be useful for ensuring reliability and failover requirements for the environment. + +Sizing for Azure Cache for Redis is determined by the tier, tier family, and capacity. Cache Names within tiers specify the sizing such as shown in these [pricing tables](https://azure.microsoft.com/en-au/pricing/details/cache/). You can start the size off in a small to moderate range such as a "P1" for Premium tier, with some consideration of anticipated active load, and scale up or down as demand is understood with the aid of [monitor Azure Cache for Redis](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/cache-how-to-monitor). + +Enterprise-grade security is inherently covered in the Azure Cache for Redis implementation because Redis instances are protected with [network isolation options](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/cache-network-isolation) and particularly with [virtual network support](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/cache-how-to-premium-vnet) in the Premium tier. There is also [detailed security information](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/security-baseline) available for hardening your implementation. + +Terraform Enterprise _Active/Active_ does not currently support the Redis cluster protocol, so you should not enable clustering for a successful _Active/Active_ setup. + +For Redis version compatibility requirements, see the Terraform Enterprise [operational mode requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements#active-active-mode). +The minimum TLS version can also be configured and defaults to 1.0 - you should explicitly set it to 1.2 for latest. + +### Normal Operation + +#### Component Interaction + +The Load Balancer routes all traffic to the Terraform Enterprise instance, which is managed by +an VM Scale Set. This is a standard round-robin distribution for now, with no accounting for current load on the nodes. The instance counts on the VM Scale Set control the number of nodes in operation and can be used to increase or decrease the number of active nodes. + +_Active/Active_ Terraform Enterprise is not currently architected to support dynamic scaling based on load or other factors. The maximum and minimum instance counts on the VM Scale Set should be set to the same value. Adding a node can be done at will bt setting these values. However, removing a node requires that the node be allowed to finish active work and stop accepting new work before being terminated. The operational documentation has the details on how to "drain" a node. + +#### Replicated Console + +The Replicated Console that allows access to certain information and realtime configuration for _Standalone_ is not available in _Active/Active_. This functionality, including generating support bundles, has been replaced with CLI commands to be executed on the nodes. The operational documentation has the details on how to utilize these commands. + +#### Upgrades + +Upgrading the Terraform Enterprise version still follows a similar pattern as with _Standalone_. However, there is not an online option with the Replicated Console. It is possible to upgrade a minor release with CLI commands in a rolling fashion. A "required" release or any change that potentially affects the shared external services will need to be done with a short outage. This involves scaling down to a single node, replacing that node, and then scaling back out. The operational documentation has the details on how these processes can operate. + +### Failure Scenarios + +#### Memory Cache + +As mentioned, the Azure Cache for Redis service at the proper tier level provides automatic replication and failover. In the event of a larger failure or any normal maintenance with proper draining, the memory cache will not be required to be restored. If it is damaged it can be re-paved, and if not it can be left to continue operation. + +### Multi-Region Implementation to Address Region Failure + +Similar to _Standalone_, _Active/Active_ Terraform Enterprise is currently architected to provide high availability within a +single region. You cannot deploy additional nodes associated to the primary cluster in different regions. It is possible to deploy to multiple regions to give you greater +control over your recovery time in the event of a hard dependency +failure on a regional service. An identical infrastructure will still need to be instantiated separately with a failover scenario resulting in control of processing being transferred to the second implementation, as described in the earlier section on this topic. In addition, this identical infrastructure will require its own Memory Cache external service instance. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/gcp.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/gcp.mdx new file mode 100644 index 0000000000..471deaf91f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/gcp.mdx @@ -0,0 +1,398 @@ +--- +page_title: GCP Reference Architecture - Terraform Enterprise +description: |- + This document provides recommended practices and a reference architecture for + HashiCorp Terraform Enterprise implementations on GCP. +--- + +# Terraform Enterprise GCP Reference Architecture + +## Introduction + +This document provides recommended practices and a reference architecture for +HashiCorp Terraform Enterprise implementations on GCP. + +## Implementation Modes + +Terraform Enterprise can be installed and function in different implementation modes with increasing capability and complexity: + +- _Standalone:_ The base architecture with a single application node that supports the standard implementation requirements for the platform. +- _Active/Active:_ This is an extension of _Standalone_ mode that adds multiple active node capability that can expand horizontally to support larger and increasing execution loads. + +Since the architectures of the modes progresses logically, this guide will present the base _Standalone_ mode first and then discuss the differences that alter the implementation into the _Active/Active_ mode. + +## Required Reading + +Prior to making hardware sizing and architectural decisions, read through the +[pre-install checklist](/terraform/enterprise/deploy/replicated/install/pre-install-checklist) +to familiarize yourself with the application components and architecture. +Further, read the [reliability and availability +guidance](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) +as a primer to understanding the recommendations in this reference +architecture. + +## Infrastructure Requirements + +-> **Note:** This reference architecture focuses on the _External Services_ operational mode. + +Depending on the chosen [operational +mode](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operational-mode-decision), the +infrastructure requirements for Terraform Enterprise range from a single Cloud +Compute VM instance for _Mounted Disk_ installations to multiple instances +connected to Cloud SQL and Cloud Storage for a stateless production +installation. + +The following table provides high-level server guidelines. Of particular +note is the strong recommendation to avoid non-fixed performance CPUs, +or “Shared-core machine types” in GCP terms, such as f1-series and g1-series instances. + +### Terraform Enterprise Server (Compute Engine VM via Regional Managed Instance Group) + +| Type | CPU | Memory | Disk | GCP Machine Types | +| ------- | ------ | --------- | ------------ | ----------------- | +| Minimum | 4 core | 15 GB RAM | 50GB/200GB\* | n1-standard-4 | +| Scaled | 8 core | 30 GB RAM | 50GB/200GB\* | n1-standard-8 | + +#### Hardware Sizing Considerations + +- \*Terraform Enterprise requires 50GB for installation, but + [GCP documentation for storage performance](https://cloud.google.com/compute/docs/disks/#performance) + recommends "to ensure consistent performance for more general use of the boot device, + use either an SSD persistent disk as your boot disk or use a standard persistent disk + that is at least 200 GB in size." + +- The minimum size would be appropriate for most initial production + deployments, or for development/testing environments. + +- The scaled size is for production environments where there is a + consistent high workload in the form of concurrent Terraform runs. + +### PostgreSQL Database (Cloud SQL PostgreSQL Production) + +| Type | CPU | Memory | Storage | GCP Machine Types | +| ------- | ------ | --------- | ------- | ---------------------------- | +| Minimum | 4 core | 16 GB RAM | 50GB | Custom PostgreSQL Production | +| Scaled | 8 core | 32 GB RAM | 50GB | Custom PostgreSQL Production | + +#### Hardware Sizing Considerations + +- The minimum size would be appropriate for most initial production + deployments, or for development/testing environments. + +- The scaled size is for production environments where there is a + consistent high workload in the form of concurrent Terraform runs. + +### Object Storage (Cloud Storage) + +A [Regional Cloud Storage](https://cloud.google.com/storage/docs/storage-classes) bucket must be +specified during the Terraform Enterprise installation for application data to be stored +securely and redundantly away from the Compute Engine VMs running the +application. This Cloud Storage bucket must be in the same region as the Compute Engine and Cloud SQL +instances. +Vault is used to encrypt all application data stored in the Cloud Storage bucket. This +allows for further [server-side +encryption](https://cloud.google.com/storage/docs/encryption/). +by Cloud Storage. + +### Other Considerations + +#### Additional GCP Resources + +In order to successfully provision this reference architecture you must +also be permitted to create the following GCP resources: + +- [Project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) +- [VPC Network](https://cloud.google.com/vpc/docs/vpc) +- [Subnet](https://cloud.google.com/vpc/docs/using-vpc) +- [Firewall](https://cloud.google.com/vpc/docs/firewalls) +- [Target Pool](https://cloud.google.com/load-balancing/docs/target-pools) +- [Forwarding Rule](https://cloud.google.com/load-balancing/docs/forwarding-rules) +- [Compute Instance Template](https://cloud.google.com/compute/docs/instance-templates/) +- [Regional Managed Instance Group](https://cloud.google.com/compute/docs/instance-groups/distributing-instances-with-regional-instance-groups) +- [Cloud DNS (optional)](https://cloud.google.com/dns/) + +#### Network + +To deploy Terraform Enterprise in GCP you will need to create new or use existing +networking infrastructure. The below infrastructure diagram highlights +some of the key components (network, subnets) and you will +also have firewall and gateway requirements. These +elements are likely to be very unique to your environment and not +something this Reference Architecture can specify in detail. + +#### DNS + +DNS can be configured external to GCP or using [Cloud DNS](https://cloud.google.com/dns/). The +fully qualified domain name should resolve to the Forwarding Rules associated with the Terraform Enterprise deployment. +Creating the required DNS entry is outside the scope +of this guide. + +#### SSL/TLS Certificates and Load Balancers + +An SSL/TLS certificate signed by a public or private CA is required for secure communication between +clients, VCS systems, and the Terraform Enterprise application server. The certificate can be specified during the +UI-based installation or in a configuration file used for an unattended installation. + +### Infrastructure Diagram - Standalone + +![gcp-infrastructure-diagram](/img/docs/RA-TFE-SA-GCP-SingleRegion.png) + +The above diagram shows the infrastructure components at a high-level. + +### Application Layer + +The Application Layer is composed of a Regional Managed Instance Group and an Instance Template +providing an auto-recovery mechanism in the event of an instance or Zone failure. + +### Storage Layer + +The Storage Layer is composed of multiple service endpoints (Cloud SQL, Cloud Storage) all +configured with or benefiting from inherent resiliency +provided by GCP. + +#### Additional Information + +- [Cloud SQL high-availability](https://cloud.google.com/sql/docs/postgres/high-availability). + +- [Regional Cloud Storage](https://cloud.google.com/storage/docs/storage-classes). + +## Infrastructure Provisioning + +The recommended way to deploy Terraform Enterprise is through use of a Terraform configuration +that defines the required resources, their references to other resources, and associated +dependencies. + +## Normal Operation + +### Component Interaction + +The Forwarding Rule routes all traffic to the Terraform Enterprise instance, which is managed by +a Regional Managed Instance Group with maximum and minimum instance counts set to one. + +The Terraform Enterprise application is connected to the PostgreSQL database via the Cloud SQL +endpoint and all database requests are routed via the Cloud SQL endpoint to the database instance. + +The Terraform Enterprise application is connected to object storage via the Cloud Storage endpoint +for the defined bucket and all object storage requests are routed to the +highly available infrastructure supporting Cloud Storage. + +### Monitoring + +There is not currently a full monitoring guide for Terraform Enterprise. The following pages include information relevant to monitoring: + +- [Log Forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging) +- [Diagnostics](/terraform/enterprise/deploy/troubleshoot/contact-support) +- [Reliability and Availability](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) + +### Upgrades + +See [the Upgrades section](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) of the documentation. + +## High Availability - Failure Scenarios + +GCP provides guidance on [designing robust systems](https://cloud.google.com/compute/docs/tutorials/robustsystems). +Working in accordance with those recommendations, the Terraform Enterprise Reference +Architecture is designed to handle different failure scenarios with +different probabilities. As the architecture evolves it will provide a +higher level of service continuity. + +### Terraform Enterprise Server + +By utilizing a Regional Managed Instance Group, a Terraform Enterprise instance can automatically recover +in the event of any outage except for the loss of an entire region. + +In the event of the Terraform Enterprise instance failing in a way that GCP can +observe, [Live Migration](https://cloud.google.com/compute/docs/instances/live-migration) +is used to move the instance to new physical hardware automatically. +In the event that Live Migration is not possible the instance will crash and be restarted +on new physical hardware automatically. Once launched, it reinitializes the software, and on completion, processing on this instance will resume as normal. + +With _External Services_ (PostgreSQL Database, Object Storage) in use, there is still some application configuration data present on the Terraform Enterprise server such as installation type, database connection settings, hostname. This data rarely changes. If the configuration on Terraform Enterprise changes you should update the +Instance Template to include the updates so that any newly +launched Compute Engine VM uses them. + +### Zone Failure + +In the event of the Zone hosting the main instances (Compute Engine and Cloud SQL) failing, +the Regional Managed Instance Group for the Compute VMs will automatically +begin booting a new one in an operational Zone. + +- Cloud SQL automatically and transparently fails over to the standby zone. + The [GCP documentation provides more + detail](https://cloud.google.com/sql/docs/postgres/high-availability) + on the exact behavior and expected impact. + +- Cloud Storage is resilient to Zone failure based on its architecture. + +See below for more detail on how each component handles Zone failure. + +### PostgreSQL Database + +Using Cloud SQL as an external database service leverages the highly +available infrastructure provided by GCP. From the GCP website: + +> _A Cloud SQL instance configured for high availability is also called a regional instance. +> A regional instance is located in two zones within the configured region, so if it cannot +> serve data from its primary zone, it fails over and continues to serve data from its secondary zone. +> ([source](https://cloud.google.com/sql/docs/postgres/high-availability))_ + +### Object Storage + +Using Regional Cloud Storage as an external object store leverages the highly available +infrastructure provided by GCP. Regional Cloud Storage buckets are resilient to Zone failure +within the region selected during bucket creation. +From the GCP website: + +> _Regional Storage is appropriate for storing data in the same regional location +> as Compute Engine instances or Kubernetes Engine clusters that use the data. +> Doing so gives you better performance for data-intensive computations, as opposed +> to storing your data in a multi-regional location. +> ([source](https://cloud.google.com/storage/docs/storage-classes))_ + +## Disaster Recovery - Failure Scenarios + +GCP provides guidance on [designing robust systems](https://cloud.google.com/compute/docs/tutorials/robustsystems). +Working in accordance with those recommendations the Terraform Enterprise Reference Architecture is designed to handle +different failure scenarios that have different probabilities. As the +architecture evolves it will continue to provide a higher level of service +continuity. + +### Data Corruption + +The Terraform Enterprise application architecture relies on multiple service endpoints +(Cloud SQL, Cloud Storage) all providing their own backup and recovery +functionality to support a low MTTR in the event of data corruption. + +### PostgreSQL Database + +Backup and restoration of PostgreSQL is managed by GCP and configured +through the GCP management console or CLI. + +Automated (scheduled) and on-demand backups are available in GCP. Review the +[backup](https://cloud.google.com/sql/docs/postgres/backup-recovery/backups) +and [restoration](https://cloud.google.com/sql/docs/postgres/backup-recovery/restore) +documentation for further guidance. + +More details of Cloud SQL (PostgreSQL) features are available [here](https://cloud.google.com/sql/docs/postgres/). + +### Object Storage + +There is no automatic backup/snapshot of Cloud Storage by GCP, so it is recommended +to script a bucket copy process from the bucket used by the Terraform Enterprise +application to a “backup bucket” in Cloud Storage that runs at regular intervals. +The [Nearline Storage](https://cloud.google.com/storage/docs/storage-classes#nearline) storage class +is identified as a solution targeted more for DR backups. From the GCP website: + +> _Nearline Storage is ideal for data you plan to read or modify on average once a month or less. +> For example, if you want to continuously add files to Cloud Storage and plan to access those +> files once a month for analysis, Nearline Storage is a great choice. +> Nearline Storage is also appropriate for data backup, disaster recovery, and archival storage. +> ([source](https://cloud.google.com/storage/docs/storage-classes#nearline))_ + +## Multi-Region Deployment to Address Region Failure + +Terraform Enterprise is currently architected to provide high availability within a +single GCP Region only. It is possible to deploy to multiple GCP Regions to give you greater +control over your recovery time in the event of a hard dependency +failure on a regional GCP service. In this section, implementation patterns to support this are discussed. + +An identical infrastructure should be provisioned in a secondary GCP +Region. Depending on recovery time objectives and tolerances for +additional cost to support GCP Region failure, the infrastructure can be +running (Warm Standby) or stopped (Cold Standby). In the event of the +primary GCP Region hosting the Terraform Enterprise application failing, the secondary +GCP Region will require some configuration before traffic is directed to +it along with some global services such as DNS. + +- [Cloud SQL cross-region read replicas](https://cloud.google.com/sql/docs/postgres/replication/cross-region-replicas) can be used in a warm standby architecture. See also [Managing Cloud SQL read replicas](https://cloud.google.com/sql/docs/postgres/replication/manage-replicas). + + - Note that read replicas do not inherently provide high availability in the sense that there can be automatic failover from the primary to the read replica. As described in the above reference, the read replica will need to be promoted to a stand-alone Cloud SQL primary instance. Promoting a replica to a stand-alone Cloud SQL primary instance is an irreversible action, so when the failover needs to be reverted, the database must be restored to an original primary location (potentially by starting it as a read replica and promoting it), and the secondary read replica will need to be destroyed and re-established. + + - GCP now offers a [high availability option for Cloud SQL](https://cloud.google.com/sql/docs/mysql/high-availability) databases which could be incorporated into a more automatic failover scenario.\* + +- [Cloud SQL database backups](https://cloud.google.com/sql/docs/postgres/backup-recovery/restoring) can be used in a cold standby architecture. + + - GCP now offers a [Point-in-time recovery](https://cloud.google.com/sql/docs/postgres/backup-recovery/pitr) option for Cloud SQL databases which could be incorporated into a backup and recovery scheme with reduced downtime and higher reliability.\* + +- [Multi-Regional Cloud Storage replication](https://cloud.google.com/storage/docs/storage-classes) must be configured so the object storage component of the Storage Layer is available in multiple GCP Regions. + +- DNS must be redirected to the Forwarding Rule acting as the entry point for the infrastructure deployed in the secondary GCP Region. + +- Terraform Enterprise in the _Standalone_ mode is an Active/Passive model. At no point should more than one Terraform Enterprise instance be actively connected to the same database instance. + +\* **Note:** We are investigating incorporating these newer CloudSQL capabilities into this reference architecture, but do not have additional details at this time. + +## Active/Active Implementation Mode + +### Overview + +As stated previously, the _Active/Active_ implementation mode is an extension of the _Standalone_ implementation mode that increases the scalability and load capacity of the Terraform Enterprise platform. The same application runs on multiple Terraform Enterprise instances utilizing the same external services in a shared model. The primary architectural and implementation differences for _Active/Active_ are: + +- It can only be run in the _External Services_ mode. +- The additional nodes are active and processing work at all times. +- In an addition to the existing external services, there is a memory cache which is currently implemented with cloud native implementations of Redis. This is used for the processing queue for the application and has been moved from the individual instance to be a shared resource that manages distribution of work. +- There are additional configuration parameters to manage the operation of the node cluster and the memory cache. + +The following sections will provide further detail on the infrastructure and implementation differences. + +### Migration to Active/Active + +If you are considering a migration from a _Standalone_ implementation to _Active/Active_, it is straightforward and there is guidance available to assist with that effort. However, you should first make a determination if the move is necessary. The _Standalone_ mode is capable of handling significant load and the first paths to supporting higher load can be simply increasing the compute power in the existing implementation. A discussion with your HashiCorp representatives may be warranted. + +Also note that if your existing architecture does not already depict what is shown and discussed above, you will likely need to make adjustments to bring it into alignment. This could be either before or during the migration. Certain tenets of the reference architecture described here are highly recommended and potentially necessary to support _Active/Active_ mode such as load balancers and scaling groups. + +### Infrastructure Diagram - Active/Active + +![gcp-aa-infrastructure-diagram](/img/docs/RA-TFE-AA-GCP-SingleRegion.png) + +The above diagram shows the infrastructure components of an _Active/Active_ implementation at a high-level. + +### Infrastructure Requirements + +#### Active Nodes + +The diagram depicts two active nodes to be concise. Additional nodes can be added by altering your configuration to launch another instance that points to the same shared external services. The number and sizing of nodes should be based on load requirements and redundancy needs. Nodes should be deployed in alternate zones to accommodate zone failure. + +The cluster is comprised of essentially independent nodes in a SaaS type model. There are no concerns of leader election or minimal or optimum node counts. When a new node enters the cluster it simply starts taking new work from the load balancer and from the memory cache queue and thus spreading the load horizontally. + +#### Memory Cache + +The GCP implementation of the memory cache is handled by [Google Cloud Memorystore services](https://cloud.google.com/memorystore). Specifically using [Memorystore for Redis](https://cloud.google.com/memorystore/docs/redis). + +[Memorystore for Redis Overview](https://cloud.google.com/memorystore/docs/redis/redis-overview) provides a high level description of the implementation options for the memory cache. A primary differentiator is Basic Tier and Standard Tier. The primary difference is that the Standard Tier offers [high availability](https://cloud.google.com/memorystore/docs/redis/high-availability)] where instances are always replicated across zones and provides 99.9% availability SLAs (note that reading from a replica is not supported). A lower testing or sandbox environment could use the Basic Tier, however, a production level environment should always use Standard Tier to gain the HA features that coincide with the other external services in the Terraform Enterprise platform. + +Memorystore for Redis service supports [realtime scaling of instance size](https://cloud.google.com/memorystore/docs/redis/scaling-instances). You can start the size off in a smaller range with some consideration of anticipated active load, and scale up or down as demand is understood with the aid of [monitoring ](https://cloud.google.com/memorystore/docs/redis/monitoring-instances). + +Enterprise-grade security is inherently covered in the Memorystore for Redis implementation because Redis instances are protected from the Internet using private IPs, and access to instances is controlled and limited to applications running on the same Virtual Private Network as the Redis instance. Additional security measures can be instituted using [IAM based access control and permissions](https://cloud.google.com/memorystore/docs/redis/access-control). However, this may add additional complication to your realtime scaling of instances. + +For Redis version compatibility requirements, see the Terraform Enterprise [operational mode requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements#active-active-mode) + +### Normal Operation + +#### Component Interaction + +The Forwarding Rule routes traffic to the Terraform Enterprise node instances, which is managed by +a Regional Managed Instance Group. This is a standard round-robin distribution for now, with no accounting for current load on the nodes. The instance counts on the Regional Managed Instance Group control the number of nodes in operation and can be used to increase or decrease the number of active nodes. + +_Active/Active_ Terraform Enterprise is not currently architected to support dynamic scaling based on load or other factors. The maximum and minimum instance counts on the Regional Managed Instance Group should be set to the same value. Adding a node can be done at will by setting these values. However, removing a node requires that the node be allowed to finish active work and stop accepting new work before being terminated. The operational documentation has the details on how to "drain" a node. + +#### Replicated Console + +The Replicated Console that allows access to certain information and realtime configuration for _Standalone_ is not available in _Active/Active_. This functionality, including generating support bundles, has been replaced with CLI commands to be executed on the nodes. The operational documentation has the details on how to utilize these commands. + +#### Upgrades + +Upgrading the Terraform Enterprise version still follows a similar pattern as with _Standalone_. However, there is not an online option with the Replicated Console. It is possible to upgrade a minor release with CLI commands in a rolling fashion. A "required" release or any change the potentially affects the shared external services will need to be done with a short outage. This involves scaling down to a single node, replacing that node, and then scaling back out. The operational documentation has the details on how these processes can operate. + +### Failure Scenarios + +#### Memory Cache + +As mentioned, the Memorystore for Redis service in Standard Tier mode provides automatic replication and failover. In the event of a larger failure or any normal maintenance with proper draining, the memory cache will not be required to be restored. If it is damaged it can be re-paved, and if not it can be left to continue operation. + +### Multi-Region Implementation to Address Region Failure + +Similar to _Standalone_, _Active/Active_ Terraform Enterprise is currently architected to provide high availability within a +single region. You cannot deploy additional nodes associated to the primary cluster in different regions. It is possible to deploy to multiple regions to give you greater +control over your recovery time in the event of a hard dependency +failure on a regional service. An identical infrastructure will still need to be instantiated separately with a failover scenario resulting in control of processing being transferred to the second implementation, as described in the earlier section on this topic. In addition, this identical infrastructure will require its own memory cache external service instance. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/index.mdx new file mode 100644 index 0000000000..dd6f5c21e2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/index.mdx @@ -0,0 +1,33 @@ +--- +page_title: Reference Architectures - Terraform Enterprise +description: >- + Links to Terraform Enterprise reference architectures for AWS, Azure, Google + Cloud Platform, and VMware. +--- + +# Terraform Enterprise Reference Architectures + +HashiCorp provides reference architectures detailing the recommended +infrastructure and resources that should be provisioned in order to +support a highly-available Terraform Enterprise deployment. + +Depending on where you choose to deploy Terraform Enterprise, +there are different services available to maximize the resiliency of +the deployment, for example, most major cloud service providers offer +a resilient relational database service offering, removing the need +for the customer to manage a complex database cluster/failover +architecture. We have taken this into consideration and created a +reference architecture for the most common deployment configurations, +making the most appropriate use of those cloud vendor services. + +~> **Note:** The discontinued clustered version of Terraform Enterprise is no longer supported, and we strongly advise all customers to move to an Active/Active installation. Please contact your support representative if you need assistance. + +## Reference Architectures + +- [Amazon Web Services](/terraform/enterprise/deploy/replicated/architecture/reference-architecture/aws) + +- [Microsoft Azure](/terraform/enterprise/deploy/replicated/architecture/reference-architecture/azure) + +- [Google Cloud Platform](/terraform/enterprise/deploy/replicated/architecture/reference-architecture/gcp) + +- [VMware](/terraform/enterprise/deploy/replicated/architecture/reference-architecture/vmware) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/vmware.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/vmware.mdx new file mode 100644 index 0000000000..1d756ace9e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/reference-architecture/vmware.mdx @@ -0,0 +1,296 @@ +--- +page_title: VMware Reference Architecture - Terraform Enterprise +description: |- + This document provides recommended practices and a reference architecture for + HashiCorp Terraform Enterprise implementations on VMware. +--- + +# Terraform Enterprise VMware Reference Architecture + +## Introduction + +This document provides recommended practices and a reference architecture for +HashiCorp Terraform Enterprise implementations on VMware. + +## Implementation Modes + +Terraform Enterprise can be installed and function in different implementation modes with increasing capability and complexity: + +- _Standalone/Mounted Disk:_ The base architecture with a single application node that supports the standard implementation requirements for the platform. +- _Active/Active:_ This is an extension of _Standalone_ mode that adds multiple active node capability that can expand horizontally to support larger and increasing execution loads. + +This guide will present the base _Standalone/Mounted Disk_ mode first and then discuss the differences that alter the implementation into the _Active/Active_ mode. + +## Required Reading + +Prior to making hardware sizing and architectural decisions, read through the +[pre-install checklist](/terraform/enterprise/deploy/replicated/install/pre-install-checklist) +to familiarise yourself with the application components and architecture. +Further, read the [reliability and availability +guidance](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) +as a primer to understanding the recommendations in this reference +architecture. + +## Infrastructure Requirements + +The [operational +mode](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operational-mode-decision) determines the +infrastructure requirements for your instance. For example, an installation in +Mounted Disk mode may require a single virtual machine, whereas a stateless +production installation may require multiple virtual machines to host the +HCP Terraform application, PostgreSQL, Redis, and external Vault servers. + +## Standalone/Mounted Disk + +This mode requires that you specify the local path for data storage. The local path should be a mounted disk from a SAN or NAS device, or some other replicated storage. This allows for rapid recovery or failover. + +If you need or want to define storage externally and independently, you can choose the _External Services_ +operational mode. This is a more complicated implementation in VMware that requires you to independently manage other services which will not be detailed in this document. You will need to deploy S3-compatible storage either by connecting to a true AWS S3 bucket or by using a compatible alternative on-prem solution, such as [Ceph](https://ceph.com/). You will also need to deploy and separately manage an external PostgreSQL database on an additional server or servers. + +Some additional information about the _External Services_ option can be found at the end of this document. + +Although it is possible for Terraform Enterprise to use an external Vault server instead of its internally managed one, we do not recommended it. External Vault usage is not addressed in this document. + +The following table provides high-level server recommendations as a guideline. +Please note, thick provision, lazy zeroed storage is preferred. Thin +provisioned is only recommended if you are using an external PostgreSQL database and external Vault server. Using thin provisioned disks when using +the internal database or Vault may result in serious performance issues. + +### Terraform Enterprise Servers + +| Type | CPU Sockets | Total Cores\* | Memory | Disk | +| ------- | ----------- | ------------- | --------- | ---- | +| Minimum | 2 | 4 | 16 GB RAM | 40GB | +| Scaled | 2 | 8 | 32 GB RAM | 40GB | + +-> **Note:** Per VMware’s recommendation, always allocate the least amount of vCPUs and cores necessary and scale the resources based on application demand. HashiCorp recommends starting with 4 CPUs and increasing if necessary. + +#### Hardware Sizing Considerations + +- The minimum size would be appropriate for most initial production + deployments, or for development/testing environments. + +- The scaled size is for production environments where there is + a consistent high workload in the form of concurrent terraform + runs. + +- Please monitor the actual CPU utilization in vCenter before making + the decision to increase the CPU allocation. + +### Other Considerations + +#### Network + +To deploy Terraform Enterprise on VMware you will need to create new or use existing networking +infrastructure that has access to any infrastructure you expect to +manage with the Terraform Enterprise server. If you plan to use your Terraform Enterprise server to manage or +deploy infrastructure on external providers (eg Amazon Web Services, Microsoft Azure or Google Cloud), you will need to make sure the Terraform Enterprise server has unimpeded access to those providers. The same goes for any other public or private datacenter the server will need to +connect with. + +#### DNS + +The fully qualified domain name should resolve to the IP address of the virtual +machine using an A record. Creating the required DNS entry is outside the scope +of this guide. + +#### SSL/TLS + +A valid, signed SSL/TLS certificate is required for secure communication between clients and +the Terraform Enterprise application server. Requesting a certificate is outside the scope +of this guide. You will be prompted for the public and private certificates during installation. + +## Infrastructure Diagram + +![vmware-mounted-disk-infrastructure-diagram](/img/docs/vmware-mounted-disk-infrastructure-diagram.png) + +### Application Layer + +The Application Layer is a VMware virtual machine running on an ESXi cluster +providing an auto-recovery mechanism in the event of virtual machine or physical server failure. + +### Storage Layer + +The Storage Layer is provided in the form of attached disk space configured with or benefiting from inherent resiliency +provided by the NAS or SAN. The primary Terraform Enterprise VM will have 2 disks which must meet the requirements detailed [here](/terraform/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements). The first disk is independent to this VM and contains the OS and Terraform Enterprise components specific to this individual install, such as configuration information. The second disk will contain Terraform Enterprise's configuration information such as Workspaces and their resulting Terraform state files. This second disk needs to be regularly backed up, for instance via replication or snapshotting inherent to your SAN or other software, at a rate that meets your desired RPO. +Similarly, the standby VM will have two disks. An OS disk that is independent to that VM and a disk which is simply a point in time copy of the primary instance's second disk. + +-> **Note:** Terraform Enterprise's storage device or service must be highly reliable and high-speed in both I/O and connectivity to meet performance requirements. Device types in the supported list will usually meet these requirements, but many standard NAS and other device types will not perform at the level required. Only use a NAS or other device type not in the supported list if you are certain it can accommodate these requirements. + +The specific selection and configuration of the storage device is not covered in this document. +For more information about high-speed and highly available storage, please see your storage vendor. +We recommend that each of these VMs be deployed as immutable architecture to enable one to easily redeploy the secondary VM when the primary has been upgraded or changed. If this is not possible a snapshot methodology inherent to Terraform Enterprise along with examples of restoring those snapshots is available at [Terraform Enterprise Automated Recovery](/terraform/enterprise/deploy/replicated/administration/infrastructure/automated-recovery). + +For more information about Terraform Enterprise's disk requirements, see [Before Installing: Disk Requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements). + +## Active/Active + +The Active/Active mode provides a higher level of availability and failover as well as horizontal scaling. It requires additional external services, and all of the requirements and instructions are available on the [Terraform Enterprise Active/Active page](/terraform/enterprise/deploy/replicated/install/automated/active-active). + +We have tested Active/Active on VMware vSphere internally, with ESXi version 7.0.1 and vCenter Server version 7.0.2.00200, but should work on any version supported by the [vSphere Provider for Terraform](https://github.com/hashicorp/terraform-provider-vsphere). + +We recommend a setup with the following: + +- A load balancer to route traffic to both Terraform Enterprise virtual machines. +- Both virtual machines located in the same physical datacenter and on the same network. High network latency between the Terraform Enterprise virtual machines and the external services may result in plan and apply issues. +- High-speed disks, as they are [critical for good performance](/terraform/enterprise/deploy/replicated/architecture/system-overview/capacity). +- Both Terraform Enterprise virtual machines can access an external Redis server, a PostgreSQL database, and an S3-compatible blob storage bucket. Terraform Enterprise will use an internal Vault server by default. Optionally, you can configure Terraform Enterprise to use an [existing Vault cluster](/terraform/enterprise/deploy/replicated/install/vault). + +An example of a recommended setup: + +![Terraform Enterprise Active/Active on VMware](/img/docs/RA-TFE-AA-VMware-SingleRegion.png) + +## Infrastructure Provisioning + +The recommended way to deploy Terraform Enterprise for production is through use of a Terraform configuration +that defines the required resources, their references to other resources and +dependencies. + +## Normal Operation + +### Component Interaction + +In Mounted Disk Mode the PostgreSQL database will be run in a local container and data will be +written to the specified path (which should be a mounted storage device, +replicated and/or backed up frequently.) In Active/Active or External Services Mod the external PostgreSQL server will be used. + +State and other data will be +written to the specified local path (which should be a mounted storage +device, replicated and/or backed up frequently) in Mounted Disk, and the S3-compatible storage in Active/Active or External Service Mode. + +Redis is used to managed job flow and does not contain stateful data. In Mounted Disk Mode and External Services this service will be started locally as a container. In Active/Active this will be an external server. + +Vault will be run in a local container and used only for transit data encryption and decryption. This stateless use of Vault provides easy recovery in the event of a Vault service failure. + +### Monitoring + +While there is not currently a full monitoring guide for Terraform Enterprise, information around +[logging](/terraform/enterprise/deploy/replicated/monitoring/logging), +[diagnostics](/terraform/enterprise//deploy/troubleshoot) +as well as [reliability and +availability](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability) +can be found on our website. + +### Upgrades + +See [the Upgrades section](/terraform/enterprise/deploy/replicated/administration/infrastructure/upgrades) of the documentation. For Active/Active you'll need to scale down to a single virtual machine before proceeding with an upgrade. + +## High Availability + +### Failure Scenarios + +VMware vSphere provides a high level of resilience in various cases +of failure, such as at the server hardware layer through vSphere High Availability (HA) and at the network layer through virtual distributed +switching. In addition, employing tools such as VMware Site Recovery Manager or utilizing stretched clusters +can assist in recovery in the case of a total data center to support failover to a DR datacenter. See the Disaster Recovery section. + +The Active/Active deployment method can provide additional failover. + +#### Terraform Enterprise Servers (VMware Virtual Machine) + +Should the _TFE-main_ server fail, it can +be recovered in place, or the virtual machine can restored to a Disaster Recovery target, to +resume service when the failure is limited to the Terraform Enterprise server layer. See the Disaster Recovery section. + +#### Single ESXi Host Failure + +In the event of a single ESXi host failure, vSphere HA will restart the Terraform Enterprise virtual +machine to a functioning ESXi host in the cluster. This restart can take up to 30 seconds for the failed virtual machine to come back online on a healthy host within the cluster. + +If VMware vSphere Fault Tolerance (FT) has been configured for the Terraform Enterprise server, the failover does not result in any visiable outage to the end user. + +#### PostgreSQL Database + +When running in _Mounted Disk_ operational mode the PostgreSQL server runs inside a +Docker container. If the PostgreSQL service fails a new container should +be automatically created. However, if the service is hung, or otherwise +fails without triggering a new container deployment, the Terraform Enterprise server +should be stopped and the standby server started. All PostgreSQL data will +have been written to the mounted disk and will then be accessible on +the standby node. + +#### Object Storage + +The object storage will be stored on the mounted disk and the +expectation is that the NAS or SAN or other highly available mounted +storage is fault tolerant and replicated or has fast recovery available. + +#### Redis (Active/Active Only) + +The Redis service does not contain stateful data and does not require backups or data sync. +The Redis deployment must satify the [requirements](/terraform/enterprise/deploy/configuration/storage/connect-redis#requirements) of Terraform Enterprise. + +## Disaster Recovery + +### Failure Scenarios + +#### Terraform Enterprise Servers (VMware Virtual Machine) + +Through deployment of two virtual machines in different ESXi clusters, +the Terraform Enterprise Reference Architecture is designed to provide improved +availability and reliability. Should the _TFE-main_ server fail, it can +be recovered, or traffic can be routed to a newly built Terraform Enterprise server, with a backup restored to it, to +resume service when the failure is limited to the Terraform Enterprise server layer. The +load balancer should be manually updated to point to the new Terraform Enterprise +VM after services have been started on it in the event of a failure. The specifics of how data should be handled in a Disaster Recovery event will depend on the operational mode. + +**For a mounted disk install:** + +If the backup method is to snapshot the virtual machine from the ESX host, file-quiesence must be enabled to ensure data consistency. The other backup option is to make use of the [Backup and Restore API](/terraform/enterprise/deploy/replicated/administration/infrastructure/backup-restore). + +Once a Disaster has been declared, or an in-place recovery after a failure is otherwise not an option, either a new virtual machine should be created and the backup from the primary should be restored into it via the API, or the virtual machine snapshot should be deployed to the the new ESX host. Please be aware, some configuration items may need to be updated; if the DR database address is different from the primary, for example. After any configuration changes, the Terraform Enterprise server will need to be restarted. + +#### Mounted Disk - Data layer - PostgreSQL Database & Object Storage + +The PostgreSQL data and object storage will be written to the mounted disk. The +expectation is that the Terraform Enterprise application data is backedup via the [Backup and Restore API](/terraform/enterprise/deploy/replicated/administration/infrastructure/backup-restore), or the entire virtual machine is backed up via snapshot (with file-quiescence enabled), and then replicated or backed up +offsite and made available to in the event of a DR. + +#### Active/Active Disaster Recovery + +You should back up and replicate the stateful external services (PostgreSQL and Blob Storage) to an offsite location to enable a disaster recovery or datacenter failover. Use service-native tools for backups rather than the [Backup/Restore API](/terraform/enterprise/deploy/replicated/administration/infrastructure/backup-restore), which is designed to help with platform migration. If you use virtual machine snapshots, you must enable `file-quiecense`. You do not need to back up the Redis instance because it does not store stateful data. + +Redeploy the Terraform Enterprise virtual machines in the restore location using the same automation as in the primary datacenter, and update names and IP addresses for the external services as is necessary, or restore the virtual machine snapshot to the target datacenter and update any configuration as needed (database and redis urls, object storage endpoint) and restart the Terraform Enterprise application. + +## External Services Storage Options + +This information is included if _External Services_ operational mode is required. + +### External Services - Object Storage Options + +An [S3 Standard](https://aws.amazon.com/s3/storage-classes/) bucket, or compatible storage, must be +specified during the Terraform Enterprise installation for application data to be stored +securely and redundantly away from the virtual servers running the Terraform Enterprise +application. This object storage must be accessible via the network to the Terraform Enterprise virtual +machine. Vault is used to encrypt all +application data stored in this location. This allows for further [server-side +encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html) +by S3 if required by your security policy. + +Recommended object storage solutions are AWS S3, Google Cloud storage, Azure blob storage. Other options for S3-compatible storage are [MinIO](https://www.minio.io/), and [Ceph](https://ceph.com/), and [ECS](https://www.delltechnologies.com/en-us/storage/ecs/index.html/), among many others. Please feel free to reach out to [support](https://www.hashicorp.com/support) with questions. + +### External Services - PostgreSQL Database + +#### External Services - PostgreSQL Database Management + +Using a PostgreSQL cluster will provide fault tolerance at the database layer. +Documentation on how to deploy a PostgreSQL cluster can be found on the [PostgreSQL +documentation page](https://www.postgresql.org/docs/9.5/static/creating-cluster.html). + +Backup and recovery of PostgreSQL will vary based on your implementation +and is not covered in this document. We do recommend regular database snapshots. + +#### External Services - PostgreSQL Database Sizing + +| Type | CPU Sockets | Total Cores | Memory | Storage | +| ---------- | ----------- | ----------- | ------------ | ------- | +| Production | 2 | 4-8 core | 16-32 GB RAM | 50GB | + +### Active/Active - Redis Server + +Redis server versions `5.x` is supported and has been tested thoroughly with Terraform Enterprise. Redis (cluster enabled) Cluster is _not_ currently supported. Options are provided for the following: + +- redis_port: Allows for connecting to a Redis server running on a nonstandard port +- redis_use_password_auth: This can be set to 1 if you are using password authentication, or 0 if not. +- redis_use_tls: Allows to enabling(1) or disabling(0) the TLS requirement + +Additional details can be found on the [Active/Active Installation page](/terraform/enterprise/deploy/replicated/install/automated/active-active). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/capacity.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/capacity.mdx new file mode 100644 index 0000000000..1bff0f13ff --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/capacity.mdx @@ -0,0 +1,74 @@ +--- +page_title: Capacity and Performance - System Overview - Terraform Enterprise +description: >- + Learn about maximum capacity and performance as well as how to adjust capacity + and memory for your instance. +--- + +# Capacity and Performance + +The maximum capacity and performance of Terraform Enterprise is dependent entirely on the resources +provided by the Linux instance it is installed on. There are a few settings that allow Terraform Enterprise's capacity to be adjusted to suit the instance. + +## Memory + Concurrency + +The amount of memory to allocate to a Terraform run and the number of concurrent runs are the primary elements in +understanding capacity above the base services. + +By default, Terraform Enterprise allocates 512 MB of memory to each Terraform run, with a default concurrency of 10 parallel runs. +Therefore, by default Terraform Enterprise requires 5.2 GB of memory reserved for runs. + +After factoring in the memory needed to run the base services that make up the application, the default memory footprint of Terraform Enterprise is approximately 4 GB. + +### Settings + +The settings for per-run memory and concurrency are available in the dashboard on port 8800, on the Settings page, under the Capacity section. They can also be set via +the [application settings JSON file when using the automated install procedure](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#available-settings). + +## Increasing Concurrency + +To increase the number of concurrent runs, adjust the `capacity_concurrency` setting. This setting is not limited by +system checks; it depends on the operator to provide enough memory to the system to accommodate the requested +concurrent capacity. For example, if `capacity_concurrency` is set to `100` and the worker memory is set to 512, the instance would require a minimum of 52 GB of memory just for Terraform runs. The rest of the Terraform Enterprise application requires a minimum of 4 GB of memory in addition to the Operating System requirements. + +## Adjusting Memory + +The default memory limit of 512 MB per Terraform run is also configurable. Note that this setting is not limited by +system checks; it depends on the operator to provide enough memory to the system to accommodate the requested limits. +If the memory limit is adjusted to 1024 MB with the default capacity of 10, the instance would require, at a minimum, +10 GB of memory reserved for Terraform runs. + +### Downward Adjustment + +We do not recommend adjusting the memory limit below 512 MB. Memory is Terraform's primary resource and it +becomes easy for it to go above smaller limits and be terminated mid-run by the Linux kernel. + +## CPU + +The required CPU resources for an individual Terraform run vary considerably, but in general they are a much more minor +factor than memory due to Terraform mostly waiting on IO from APIs to return. + +Our rule of thumb is 10 Terraform runs per CPU core, with 2 CPU cores allocated for the base Terraform Enterprise services. +So a 4-core instance with 16 GB of memory could comfortably run 20 Terraform runs, if the runs are allocated the default +512 MB each. + +As of the `v202109-1` Terraform Enterprise release, you can use the `capacity_cpus` Replicated configuration option to set the maximum number of CPU cores that can be allocated to a Terraform run. When `capacity_cpus` is set, the configuration places a hard quota on the number of cores that a Terraform operation and underlying provider plugin logic can consume. This can be an effective tool to prevent one expensive workspace from +monopolizing the CPU resources of the host. + +## Disk + +The amount of disk storage available to a system plays a small role in the capacity of an instance. +A root volume with 200 GB of storage can sustain a capacity well over 100 concurrent runs. + +## Disk I/O + +Because of the amount of churn caused by container creation as well as Terraform state management, +highly concurrent setups will begin pushing hard on disk I/O. In cloud environments like AWS that limit disk +I/O to IOPS that are credited per disk, it's important to provision a minimum number to prevent I/O related +stalls. Low disk I/O can create significant performance issues. + +This resource is harder to predict than memory or CPU usage because it varies per Terraform module, +but we generally recommend a minimum of 50 IOPS per concurrent Terraform run. So if an instance is configured for 10 concurrent runs, the disk should have 500 IOPS allocated. For reference, on AWS, an EBS volume +with an allocated size of 250 GB comes with a steady state of 750 IOPS. + +We recommend using a disk with a minimum of 500 IOPS, but high load systems should consider increasing this significantly. For example, a production instance with a consistently high level of utilization and a concurrency of 10 should ideally have a disk with about 3,000 IOPS. Internal testing has shown performance increases with additional IOPs up to 8,000. Scaling the disk beyond 8,000 IOPs does not significantly improve performance. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/data-security.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/data-security.mdx new file mode 100644 index 0000000000..6c3b2930fa --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/data-security.mdx @@ -0,0 +1,57 @@ +--- +page_title: Data Security - Architectural Details - Terraform Enterprise +description: >- + Learn which parts of the application contain sensitive data and what storage + and encryption methods we use. +source: terraform-docs-common +--- + +# Data Security + +HCP Terraform takes the security of the data it manages +seriously. This table lists which parts of the HCP Terraform and Terraform Enterprise app can contain sensitive data, what storage is used, and what encryption is used. + +### HCP Terraform and Enterprise + +| Object | Storage | Encrypted | +| :----------------------------------- | :----------- | :----------------------- | +| Ingressed VCS Data | Blob Storage | Vault Transit Encryption | +| Terraform Plan Result | Blob Storage | Vault Transit Encryption | +| Terraform State | Blob Storage | Vault Transit Encryption | +| Terraform Logs | Blob Storage | Vault Transit Encryption | +| Terraform/Environment Variables | PostgreSQL | Vault Transit Encryption | +| Organization/Workspace/Team Settings | PostgreSQL | No | +| Account Password | PostgreSQL | bcrypt | +| 2FA Recovery Codes | PostgreSQL | Vault Transit Encryption | +| SSH Keys | PostgreSQL | Vault Transit Encryption | +| User/Team/Organization Tokens | PostgreSQL | HMAC SHA512 | +| OAuth Client ID + Secret | PostgreSQL | Vault Transit Encryption | +| OAuth User Tokens | PostgreSQL | Vault Transit Encryption | + +### Terraform Enterprise Specific + +| Object | Storage | Encrypted | +| :--------------------------- | :--------- | :----------------------- | +| Twilio Account Configuration | PostgreSQL | Vault Transit Encryption | +| SMTP Configuration | PostgreSQL | Vault Transit Encryption | +| SAML Configuration | PostgreSQL | Vault Transit Encryption | +| Vault Unseal Key | PostgreSQL | ChaCha20+Poly1305 | + +## Vault Transit Encryption + +The [Vault Transit Secret Engine](/vault/docs/secrets/transit) +handles encryption for data in-transit and is used when encrypting data from the +application to persistent storage. + +## Blob Storage Encryption + +All objects persisted to blob storage are symmetrically encrypted prior to being +written. Each object is encrypted with a unique encryption key. Objects are +encrypted using 128 bit AES in CTR mode. The key material is processed +through the [Vault transit secret engine](/vault/docs/secrets/transit), +which uses the default transit encryption cipher (AES-GCM with a 256-bit AES key +and a 96-bit nonce), and stored alongside the object. This pattern is called envelope encryption. + +The Vault transit secret engine's +[datakey generation](/vault/api-docs/secret/transit#generate-data-key) creates the encryption key material using bit material from the kernel's cryptographically secure pseudo-random +number generator (CSPRNG) as the `context` value. Blob storage encryption generates a unique key for each object and relies on envelope encryption, so Vault does not rotate the encryption key material for individual objects. The root encryption keys within the envelope encryption scheme are rotated automatically by HCP Terraform every 365 days. These keys are not automatically rotated within TFE. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/index.mdx new file mode 100644 index 0000000000..12b1ed68d5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/index.mdx @@ -0,0 +1,11 @@ +--- +page_title: System Overview - Terraform Enterprise +description: >- + Learn about the architecture and operational characteristics of Terraform Enterprise. +--- + +# System Overview + +This section collects information about the architecture and operational characteristics of Terraform Enterprise. + +For the most part, documents in this section are not intended as task-oriented instructions. Instead, they are offered as background information to help inform your own proactive administration, maintenance, and architecture practices. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/reliability-availability.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/reliability-availability.mdx new file mode 100644 index 0000000000..1f7460bfa3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/reliability-availability.mdx @@ -0,0 +1,143 @@ +--- +page_title: Reliability and Availability - System Overview - Terraform Enterprise +description: >- + Learn about the components that determine reliability and how to recover from + failures in each operation mode. +--- + +# Reliability and Availability + +This section covers details relating to the reliability and availability of +Terraform Enterprise installations. This documentation may be +useful to customers evaluating Terraform Enterprise or operators responsible for installing and +maintaining Terraform Enterprise. + +## Components + +Terraform Enterprise consists of several distinct components that each play a +role when considering the reliability of the overall system: + +- **Application Layer** + + - _TFE Core_ - A Rails application at the center of Terraform Enterprise; + consists of web frontends and background workers + + - _TFE Services_ - A set of Go services that provide various pieces of key + functionality for Terraform Enterprise + + - _Terraform Workers_ - A fleet of isolated execution environments that + perform Terraform Runs on behalf of Terraform Enterprise users + +- **Coordination Layer** + + - _Redis_ - Used for Rails caching and coordination between Terraform Enterprise Core's web + and background workers + +- **Storage Layer** + + - _PostgreSQL Database_ - Serves as the primary store of Terraform + Enterprise's application data such as workspace settings and user settings + + - _Blob Storage_ - Used for storage of Terraform state files, plan files, + configuration, and output logs + + - _HashiCorp Vault_ - Used for encryption of sensitive data. There are + two types of Vault data in Terraform Enterprise - + [key material](/vault/docs/concepts/seal) and + [storage backend data](/vault/docs/configuration/storage). + + - _Configuration Data_ - The information provided and/or generated at + install-time (e.g. database credentials, hostname, etc.) + +## Operation Modes + +This section describes how to set up your Terraform Enterprise deployment to recover from +failures in the various operational modes (_Mounted Disk_, _External_ +_Services_). The operational mode is selected at install time and can not be +changed once the install is running. + +The below tables explain where each data type in the +[Storage Layer](#components) is stored and +the corresponding snapshot and restore procedure. For the data types that use +Terraform Enterprise's built-in snapshot and restore function, follow +[these instructions](/terraform/enterprise/deploy/replicated/administration/infrastructure/automated-recovery). For the data types that do +**not** use the built-in functionality, backup and restore is the responsibility +of the user. + +_Data Location_ + +| | Configuration | Vault | PostgreSQL | Blob Storage | +| ------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------- | -------------------------- | +| _Mounted Disk_ | Stored in Docker volumes on instance | Key material on host in `/var/lib/tfe-vault`, storage backend is mounted disk PostgreSQL | Stored in mounted disks | Stored in mounted disks | +| _External Services_ | Stored in Docker volumes on instance | Key material on host in `/var/lib/tfe-vault`, storage backend is external PostgreSQL | Stored in external service | Stored in external service | +| External Vault | - | Key material in external Vault with user-defined storage backend | - | - | + +_Backup and Restore Responsibility_ + +| | Configuration | Vault | PostgreSQL | Blob Storage | +| ------------------- | -------------------- | -------------------- | ---------- | ------------ | +| _Mounted Disk_ | Terraform Enterprise | Terraform Enterprise | User | User | +| _External Services_ | Terraform Enterprise | Terraform Enterprise | User | User | +| External Vault | - | User | - | - | + +### Mounted Disk + +_PostgreSQL Database_ and _Blob Storage_ use mounted disks for their +data. Backup and restore of those volumes is the responsibility of the user, and +is not managed by Terraform Enterprise's built-in systems. + +_Vault Data_ is stored in PostgreSQL and accordingly lives on the mounted disk. As +long as the user has restored the mounted disk successfully, the built-in restore +mechanism will restore Vault operations in the event of a failure. + +_Configuration Data_ for the installation is stored in Docker +volumes on the instance. The built-in snapshot mechanism can package up the +Configuration data and store it off the instance, and the built-in restore +mechanism can recover the configuration data and restore +operation in the event of a failure. +Configure snapshot and restore by following the [automated recovery instructions](/terraform/enterprise/deploy/replicated/administration/infrastructure/automated-recovery). + +If the instance running Terraform Enterprise is lost, the use of mounted disks +means no state data is lost. + +### External Services + +In the _External Services_ operation mode, the +**Application Layer** and **Coordination Layer** execute on a Linux instance, +but the **Storage Layer** is configured to use external services in the form of +a PostgreSQL server and an S3-compatible Blob Storage. + +The maintenance of PostgreSQL and Blob Storage are handled by the user, +which includes backing up and restoring if necessary. + +_Vault Data_ is stored in PostgreSQL. As long as PostgreSQL has been restored +successfully by the user, the built-in restore mechanism will restore Vault +operations in the event of a failure. + +_Configuration Data_ for the installation is stored in Docker +volumes on the instance. The built-in snapshot mechanism can package up the +data and store it off the instance, and the built-in restore +mechanism can recover the data and restore operation in the event of a failure. +Configure snapshot and restore by following the [automated recovery instructions](/terraform/enterprise/deploy/replicated/administration/infrastructure/automated-recovery). + +If the instance running Terraform Enterprise is lost, the use of +external services means no state data is lost. + +-> **NOTE:** Customers running an [optional external Vault cluster](/terraform/enterprise/deploy/replicated/install/vault) are +responsible for backing up the Vault data and restoring it if necessary. + +### Availability During Upgrades + +Upgrades use the installer dashboard. +Once an upgrade has been been detected (either online or airgap), the new code +is imported. Once ready, all services on the instance are restarted running +the new code. The expected downtime is between 30 seconds and 5 minutes, +depending on whether database updates have to be applied. + +Only application services are changed during the upgrade; data is not backed up +or restored. The only data changes that may occur during upgrade are the application of +migrations the new version might apply to the _PostgreSQL Database_. + +When an upgrade is ready to start the new code, the system waits for all +Terraform runs to finish before continuing. Once the new code has started, the +queue of runs is continued in the same order. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/security-model.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/security-model.mdx new file mode 100644 index 0000000000..0a51ae8fe6 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/architecture/system-overview/security-model.mdx @@ -0,0 +1,29 @@ +--- +page_title: Security Model- System Overview - Terraform Enterprise +description: >- + Learn the organizational roles required for security and our recommendations + for securely operating Terraform Enterprise. +--- + +# Terraform Enterprise Security Model + +This page explains the aspects of the Terraform security model that are unique to Terraform Enterprise. We recommend also reviewing the core concepts in [HCP Terraform Security model](/terraform/cloud-docs/architectural-details/security-model). + +@include "replicated-and-fdo/architecture/security-model-partial.mdx" + +#### Restrict Terraform Build Worker Metadata Access + +By default, Terraform Enterprise does not prevent Terraform operations from accessing the instance metadata service, which may contain IAM credentials or other sensitive data. Refer to [AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html), [Azure](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service?tabs=windows), or [Google Cloud](https://cloud.google.com/compute/docs/storing-retrieving-metadata) documentation for more information on this service. + +Terraform Enterprise allows you to restrict access to the metadata endpoint from Terraform operations, preventing workspaces from reading any data from the metadata service. You can do this by: + +- Visiting the installer dashboard "Settings" page and enabling “Restrict Terraform Build Worker Instance Metadata Access” under the “Advanced Configuration” section. +- Setting [restrict_worker_metadata_access](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#restrict_worker_metadata_access) in the application settings file. + +We recommend enabling this setting to prevent Terraform operations from accessing the instance metadata endpoint, unless you are relying on the [instance profile to provide default credentials to workspaces](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#instance-profile-as-default-credentials). + +#### Disable Unneeded Dashboard UI Access + +For standalone deployments, port 8800 is reserved for the [Replicated admin console](/terraform/enterprise/application-administration/admin-access), which is used for configuring Terraform Enterprise. This port should only be exposed to infrastructure admins. If you choose to configure Terraform Enterprise with the [automated process](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer), you can disable the Replicated admin console by passing the `disable-replicated-ui` argument to the installation script: + +`sudo bash ./install.sh disable-replicated-ui` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/index.mdx new file mode 100644 index 0000000000..a5bb45af0b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/index.mdx @@ -0,0 +1,24 @@ +--- +page_title: Legacy Deployment Overview (Replicated) - Terraform Enterprise +description: >- + Learn about the history and context of the Terraform Enterprise Replicated deployment option. +--- + +# Terraform Enterprise on Replicated + +This topic provides overview information about the Replicated deployment option for Terraform Enterprise. Deploying Terraform Enterprise to Replicated is deprecated. Refer to [Terraform Enterprise deployment overview](/terraform/enterprise/deploy) for information about deploying to the supported runtime environments. + + + +The Replicated deployment option is limited to customers who purchased Terraform Enterprise before January 2024. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + +The final Replicated release of Terraform Enterprise will be in March 2025. HashiCorp will support this release until April 1, 2026. + +To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by November 2024. For more information, refer to [Terraform Enterprise deployment overview](/terraform/enterprise/deploy) or contact your HashiCorp account representative. + + + +Before Terraform Enterprise v202309-1, you could _only_ deploy Terraform Enterprise with Replicated. Introduced in v202309-1, Terraform Enterprise supports more [flexible deployment options](/terraform/enterprise/deploy/), such as Docker Engine and Kubernetes. If Terraform Enterprise is currently deployed to Replicated today and want to migrate your Terraform Enterprise installation to an alternate deployment option, [refer to our migration guide](/terraform/enterprise/deploy/replicated-migration). + +You can deploy Terraform Enterprise using the [Replicated Native Scheduler](https://help.replicated.com/docs/native/getting-started/overview/), bundling Replicated with Terraform Enterprise. Replicated provides self-managed platform capabilities such as installation, upgrade, container orchestration, platform administration, license management, and support bundles. + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/active-active.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/active-active.mdx new file mode 100644 index 0000000000..6b848e34ab --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/active-active.mdx @@ -0,0 +1,325 @@ +--- +page_title: Automated Installation - Active/Active - Terraform Enterprise +description: >- + Use active/active architecture to increase the reliability and performance of Terraform Enterprise. Learn how to prepare for an external Redis server, update configuration files, connect to external Redis, and then scale to two nodes. +--- + +# Terraform Enterprise Active/Active + +When your organization requires increased reliability or performance from Terraform Enterprise that your current single application instance cannot provide, it is time to scale to the Active/Active architecture. + +Before scaling to Active/Active, you should weigh its benefits against increasing operational complexity. Specifically, consider the following aspects of the Active/Active architecture: + +- Hard requirement of a completely automated installation +- Observability concerns when monitoring multiple instances +- Custom automation required to manage the lifecycle of application nodes +- [CLI-based commands](/terraform/enterprise/deploy/replicated/administration/infrastructure/admin-cli) for administration instead of the Replicated Admin Console + +-> **Note**: Please contact your Customer Success Manager before attempting to follow this guide. They will be able to walk you through the process to make it as seamless as possible. + +### Prerequisite + +As mentioned above, the Active/Active architecture requires an existing [automated installation](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer) of Terraform Enterprise that follows our [best practices for deployment](/terraform/enterprise/deploy/replicated/architecture/reference-architecture). + +The primary requirement is an auto scaling group (or equivalent) with a single instance running Terraform Enterprise. This ASG should be behind a load balancer and can be exposed to the public Internet or not depending on your requirements. As mentioned earlier, the installation of the Terraform Enterprise application should be automated completely so that the auto scaling group can be scaled to zero and back to one without human intervention. + +-> **Note**: Active/Active installations on VMware infrastructure also require you to configure a Load Balancer to route traffic across the Terraform Enterprise servers. This documentation does not cover that setup. While auto-scaling groups are not available via native vCenter options, you must still configure a fully automated deployment. You must also reduce the available servers to one server for upgrades, maintenance, and support. + +The application itself must be using [External Services](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operational-mode-decision) mode to connect to an external PostgreSQL database and object storage. + +All admin and application configuration must be automated via your settings files and current with running configuration, i.e. it cannot have been altered via the Replicated Admin Console and not synced to the file. Specifically, you should be using the following configuration files: + +- `/etc/replicated.conf` - contains the configuration for the Replicated installer +- `/etc/ptfe-settings.json` - contains the configuration for the Terraform Enterprise application + +-> **Note**: The location for the latter is controlled by the "ImportSettingsFrom" setting in `/etc/replicated.conf` and is sometimes named `settings.json` or `replicated-tfe.conf` + +The requirement for automation is two-fold. First, the nodes need to be able to spin up and down without human intervention. More importantly though, you will need to ensure configuration is managed in this way going forward as the Replicated Admin Console will be disabled. **The Replicated Admin Console does not function correctly when running multiple nodes and must not be used**. + +### Step 1: Prepare to Externalize Redis + +#### Prepare Network + +There are new access requirements involving ingress and egress: + +- **Port 6379** (or the port the external Redis will be configured to use) must be open between the nodes and the Redis service +- **Port 8201** must be open between the nodes to allow Vault to run in [High Availability](/vault/docs/internals/high-availability) mode +- **Port 8800** should now be closed, as the Replicated Admin Console is no longer available when running multiple nodes + +#### Provision Redis + +Externalizing Redis allows multiple active application nodes. Terraform Enterprise works with the native Redis services from AWS, Azure, and GCP, and installs as a standard product on VMware machines. +The Redis deployment must satify the [requirements](/terraform/enterprise/deploy/configuration/storage/connect-redis#requirements) of Terraform Enterprise. + +-> **Note**: Please see the cloud-specific configuration guides at the end of this document for details [here](#appendix-1-aws-elasticcache). + +### Step 2: Update your Configuration File Templates + +Before installing, you need to make changes to the templates for the configuration files mentioned earlier in the prerequisites. + +#### Update Installer Settings + +The existing settings for the installer and infrastructure (`replicated.conf`) are still needed and require to be expanded. Please see documentation for the existing options [here](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#installer-settings). + +##### Pin Your Version + +To upgrade to the Active/Active functionality and for ongoing upgrades, you need to pin your installation to the appropriate release by setting the following: + +| **Key** | **Description** | **Specific Format Required** | +| --------------- | ------------------------------------------- | ---------------------------- | +| ReleaseSequence | Refers to a version of Terraform Enterprise | **Yes**, integer. | + +The following example pins the deployment to the the [v202101-1](/terraform/enterprise/releases/2021/v202101-1) release of Terraform Enterprise (which is the first to support multiple nodes): + +```json +{ + "ReleaseSequence": 504 +} +``` + +#### Update Application Settings + +The existing settings for the Terraform Enterprise application (`ptfe-settings.json`) are still needed and require to be expanded. Please see documentation for the existing options [here](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#application-settings). + +##### Enable Active/Active + +| **Key** | **Required Value** | **Specific Format Required** | +| -------------------- | ------------------ | ---------------------------- | +| enable_active_active | “1” | **Yes**, string. | + +```json +{ + "enable_active_active": { + "value": "1" + } +} +``` + +##### Configure External Redis + +The settings for the Terraform Enterprise application must also be expanded to support an external Redis instance: + +| **Key** | **Required Value** | **Specific Format Required** | +| ------------------------- | --------------------------------------------------------------------------------- | ---------------------------- | +| redis_host | Hostname of an external Redis instance which is resolvable from the Terraform Enterprise instance. | **Yes**, string. | +| redis_port | Port number of your external Redis instance. | **Yes**, string. | +| redis_use_password_auth\* | Set to `1`, if you are using a Redis service that requires a password. | **Yes**, string. | +| redis_pass\* | Password used to authenticate to Redis. | **Yes**, string. | +| redis_use_tls\* | Set to `1` if you are using a Redis service that requires TLS. | **Yes**, string. | + +_\* Fields marked with an asterisk are only necessary if your particular external Redis instance requires them._ + +For example: + +```json +{ + "redis_host": { + "value": "someredis.host.com" + }, + "redis_port": { + "value": "6379" + }, + "redis_use_password_auth": { + "value": "1" + }, + "redis_pass": { + "value": "somepassword" + }, + "redis_use_tls": { + "value": "1" + } +} +``` + +-> **Note:** To use in-transit encryption with GCP Memorystore for Redis, you must [download the CA certificate](https://cloud.google.com/memorystore/docs/redis/enabling-in-transit-encryption#downloading_the_certificate_authority) for your Redis instance and configure it within the `ca_certs` Terraform Enterprise application setting. Additionally, you must ensure that the `redis_port` and `redis_use_tls` settings are configured correctly. + +##### Add Encryption Password + +!> The Encryption Password value must be added to the config and is **required to be identical between node instances** for the Active/Active architecture to function: + +| **Key** | **Description** | **Value can change between deployments?** | **Specific Format Required** | +| ------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------- | +| enc_password | Used to encrypt sensitive data ([docs](/terraform/enterprise/deploy/replicated/install/automated/encryption-password)) | **No.** Changing will make decrypting existing data impossible. | No | + +```json +{ + "enc_password": { + "value": "767fee4e6046de48943df2decc55f3cd" + } +} +``` + +-> **Note**: In versions prior to `v202104-1` the following values were also required to be set: `install_id`, `root_secret`, `user_token`, `cookie_hash`, `archivist_token`, `internal_api_token`, `registry_session_secret_key` (HEX), and `registry_session_encryption_key` (HEX). These values are no longer required but will still work if they are still set by your configuration. + +### Step 3: Connect to External Redis + +Once you are prepared to include the modified configuration options in your configuration files, you must connect a single node to your newly provisioned Redis service by rebuilding your node instance with the new settings. + +#### Re-provision Terraform Enterprise Instance + +Terminate the existing instance by scaling down to zero. Once terminated, you can scale back up to one instance using your revised configuration. + +#### Wait for Terraform Enterprise to Install + +It can take up to 15 minutes for the node to provision and the Terraform Enterprise application to be installed and respond as healthy. You can monitor the status of the node provisioning by watching your auto scaling group in your cloud’s web console. To confirm the successful implementation of the Terraform Enterprise application you can SSH onto the node and run the following command to monitor the installation directly: + +```bash +replicatedctl app status +``` + +Which will output something similar to the following: + +```json +[ + { + "AppID": "218b78fa2bd6f0044c6a1010a51d5852", + "Sequence": 504, + "PatchSequence": 0, + "State": "starting", + "DesiredState": "started", + "IsCancellable": false, + "IsTransitioning": true, + "LastModifiedAt": "2021-01-07T21:15:11.650385151Z" + } +] +``` + +Installation is complete once `isTransitioning` is `false` and `State` is `started`. + +Refer to the [Admin CLI Commands](/terraform/enterprise/deploy/replicated/administration/infrastructure/admin-cli) documentation for more status and troubleshooting commands. + +#### Validate Application + +With installation complete, it is time to validate the new Redis connection. Terraform Enterprise uses Redis both as a cache for API requests and a queue for long running jobs, e.g. Terraform Runs. Test the latter behavior by running real Terraform plans and applies through the system. + +Once you are satisfied the application is running as expected, you can move on to step 4 to scale up to 2 nodes. + +### Step 4: Scale to Two Nodes + +You can now safely change the number of instances in your Auto Scaling Group ( or equivalent) to two. + +#### Disable the Replicated Admin Console + +Before scaling beyond the first node, you must disable the Replicated Admin Console as mentioned earlier in this guide. This is done by adding the `disable-replicated-ui` flag as a parameter when you call the install script, as such: + +``` +sudo bash ./install.sh disable-replicated-ui +``` + +Locate where the `install.sh` script is run as part of your provisioning/installation process and add the parameter. If there are other parameters on the same line, they should be left in place. + +#### Scale Down to Zero Nodes + +Scale down to zero nodes to fully disable the admin dashboard. Once the existing instance has terminated... + +#### Scale Up to Two Nodes + +Now that you have tested your external Redis connection change the min and max instance count of your Auto Scaling Group to 2 nodes. + +#### Wait for Terraform Enterprise to Install + +You need to wait up to 15 minutes for the application to respond as healthy on both nodes. Monitor the status of the install with the same methods used previously for one node in Step 3. + +-> **Note**: Each node needs to be checked independently. + +#### Validate Application + +Finally, confirm the application is functioning as expected when running multiple nodes. Run Terraform plan and applies through the system (and any other tests specific to your environment) like you did to validate the application in Step 3. + +Confirm the general functionality of the Terraform Enterprise UI to validate the tokens you added in Step 2 are set correctly. Browse the `Run` interface and your organization's private registry to confirm your application functions as expected. + +@include "replicated-and-fdo/admin/active-active-scaling-partial.mdx" + + +## Appendix 1: AWS ElasticCache + +The following example Terraform configuration shows how to configure a replication group for use with TFE: + +In this example, the required variables are: + +- **vpc_id** is the ID of VPC where Terraform Enterprise application will be deployed +- **subnet_ids** are the IDs of Subnets within the VPC to use for the ElastiCache Subnet Group +- **security_group_ids** are the IDs of Security Groups within the VPC that will be attached to Terraform Enterprise instances for Redis ingress +- **availability_zones** are the zones within the VPC to deploy the ElastiCache setup to + +```terraform +resource "aws_elasticache_subnet_group" "tfe" { + name = "tfe-test-elasticache" + subnet_ids = var.subnet_ids +} + +resource "aws_security_group" "redis_ingress" { + name = "external-redis-ingress" + description = "Allow traffic to redis from instances in the associated SGs" + vpc_id = var.vpc_id + + ingress { + description = "Terraform Enterprise ingress to redis" + from_port = 7480 + to_port = 7480 + protocol = "tcp" + security_groups = var.security_group_ids + } +} + +resource "aws_elasticache_replication_group" "tfe" { + node_type = "cache.m4.large" + replication_group_id = "tfe-test-redis" + replication_group_description = "External Redis for TFE." + + apply_immediately = true + at_rest_encryption_enabled = true + auth_token = random_pet.redis_password.id + automatic_failover_enabled = true + availability_zones = var.availability_zones + engine = "redis" + engine_version = "7.0" + num_cache_clusters = length(var.availability_zones) + parameter_group_name = "default.redis7" + port = 7480 + security_group_ids = [aws_security_group.redis_ingress.id] + subnet_group_name = aws_elasticache_subnet_group.tfe.name + transit_encryption_enabled = true +} +``` + +## + +## Appendix 2: GCP Memorystore for Redis + +-> **Note**: Memorystore on Google Cloud does not support persistence, so encryption at rest is not an option. + +Requirements/Options: + +- **authorized_network** - The network you wish to deploy the instance into. Internal testing was done using the same network Terraform Enterprise is deployed into. If a different network is used, the customer needs to ensure the 2 networks are open on port **6379**. +- **memory_size_gb** - How much memory to allocate to Redis. Initial testing was done with just 1GB configured. Larger deployments may require additional memory. (HCP Terraform uses an m4.large, which is just 6GB of memory, for reference.) +- **location_id** - What region to deploy into - should be the same one Terraform Enterprise is deployed into. If Standard_HA tier is selected, an alternative_location_id will also need to be provided as a failover location. +- **redis_version** - Redis `6.x` and `7.x` are the fully tested and supported version of Redis for Terraform Enterprise. Redis `7.x` is the recommended version. + +The default example provided on the provider page can be used to deploy memorystore [here](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/redis_instance). The host output of the resource can then be provided to the terraform module in order to configure connectivity. + +You may consider using other options in the configuration depending on your requirements, such as including the **auth_enabled** flag set to true, which must then be accompanied by including an additional Terraform Enterprise configuration item called **redis_password** set to the value returned in the **auth_string** attribute from the memorystore resource. + +## + +## Appendix 3: Azure Cache for Redis + +-> **Note**: Azure Cache on Azure only supports persistence and encryption with their Premium tier. All other tiers, Basic and Standard, do not support data persistence. + +The minimum instance size for Redis to be used with Terraform Enterprise is 6 GiB. For Azure, this allows for some minimum configurations across the 3 tiers using Cache Names for their different Tiers. Our recommendations on cache sizing for Azure Cache for Redis is in the table below: + +| | **Basic** | **Standard** | **Premium** | +| ------------------ | --------- | ------------ | ----------- | +| **Cache** **Name** | C3 | C0 | P2 | + +Make sure you configure the minimum TLS version to the Terraform Enterprise supported version of 1.2 as the Azure resource defaults to 1.0. The default port for Azure Cache for Redis is 6380 and will need to be modified in the Application Settings `ptfe-replicated.conf` in order for Terraform Enterprise to connect to Azure Cache for Redis. + +The default example provided on the provider page can be used to deploy Azure Cache for Redis [here](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/redis_cache). The outputs of the resource can then be provided to the Terraform module in order to configure connectivity + +## + +## Appendix 4: Redis on VMware + +Redis on VMware was tested with a virtual machine with 2 CPUs and 8 GB of memory running Ubuntu 20.04. Both Redis v6 and v7 are supported. A full list of supported Operating Systems can be found on the [Pre-Install Checklist](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operating-system-requirements). + +The sizing of your Redis server will depend on your company or organization's workload. Monitoring of the virtual machine and resizing based on utilization is recommended. More details on memory utilization can be found on [Redis' website](https://redis.io/topics/memory-optimization). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/automating-initial-user.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/automating-initial-user.mdx new file mode 100644 index 0000000000..c042dfe2ec --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/automating-initial-user.mdx @@ -0,0 +1,129 @@ +--- +page_title: Automating Initial User - Install and Config - Terraform Enterprise +description: >- + Use the `/admin/initial-admin-user` endpoint to create the initial admin user. Generate an initial admin creation token and then create the initial admin user with the HTTP API. +--- + +# Terraform Enterprise - Automating Initial User Creation + +After Terraform Enterprise is installed, the initial admin user must then be created to begin using the product. +Normally this user is created by opening the application from the installer dashboard. However, if further automation is desired, an API is available to create this user. + +## Initial Admin Creation Token (IACT) + +To create the initial admin user via the API, the request must be authenticated with the Initial Admin Creation Token (IACT). This token +can only be used to create the admin user when there are no users configured in the system. The IACT can be retrieved in several different ways. + +### Shell Command or Automated Deployment Script + +After installation, run the following from a shell connected to your Terraform Enterprise instance: + +```shell +replicated admin --tty=0 retrieve-iact +``` + +If you want to create the initial user in an automated deployment script, run a command that lets you capture the IACT. The following example command outputs the complete IACT with the carriage return character removed. The `--tty=0` flag enables the command to run successfully in automation, such as cloud-init. Without this flag set, the command will return an empty string: + +```shell +initial_token=$(replicated admin --tty=0 retrieve-iact | tr -d '\r') +``` + +The command outputs the complete IACT with the carriage return character removed, which facilitates use in automation. + +### Via API + +The option `iact_subnet_list` can be set to a CIDR mask that will allow clients in that address range to query the retrieval API directly. This allows installers the ability to create the installation and then immediately request the IACT token without running a command on the installation machine. + +~> NOTE: `iact_subnet_list` has no default value. If unset, no clients will be able to request the IACT token via the API. + +The API will be relative to the installation, for example `https://tfe.mycompany.com/admin/retrieve-iact`, with `/admin/retrieve-iact` being the path that returns the token. + +When this feature is used, it is governed by another setting: `iact_subnet_time_limit`. This is a time limit, measured from the installation starting, that controls external access to the IACT. By default this is set to 60 minutes, meaning that during the initial 60 minutes after the installation boots, the API can be used by a client within the subnet list. After that time, access is not allowed. + +If a customer wishes to disable the time limit and allow access to the IACT forever, set the limit to `unlimited`. + +## Initial Admin Creation API + +With the IACT in hand, the initial admin creation API can now be used. This API is available under the path `/admin/initial-admin-user` of your primary hostname. For instance, if your Terraform Enterprise instance was located at `tfe.mycompany.com`, the initial admin creation API would be `https://tfe.mycompany.com/admin/initial-admin-user`. + +This API requires the IACT as well as a JSON document describing the username, email address, and password of the initial admin user. + +## Creating the Initial Admin User API + +`POST /admin/initial-admin-user` + +| Status | Response | Reason | +| ------- | ------------------- | -------------------------------------------------------------- | +| [200][] | JSON document | Successfully created the user | +| [404][] | JSON error document | Unauthorized to perform action | +| [422][] | JSON error document | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | JSON error document | Failure during user creation | + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +### Query Parameters + +These are standard URL query parameters; remember to percent-encode values if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| --------- | --------------------------------------------------------- | +| `token` | **Required.** The IACT token retrieved via API or command | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------- | ------ | ------- | ------------------------------------ | +| `username` | string | | The username to assign the new user. | +| `email` | string | | The email address of the new user. | +| `password` | string | | The password of the new user. | + +### Response Body + +The POST endpoint will return a JSON object with the following properties. + +| Key path | Type | Description | +| -------- | ------ | -------------------------------------------------------------------------- | +| `status` | string | Either `"created"` or `"error"`. | +| `token` | string | If status is `"created"`, this contains a Terraform Enterprise user token for the new user. | +| `error` | string | If status is `"error"`, this contains the reason for the error. | + +### Sample Payload + +```json +{ + "username": "manage", + "email": "it@mycompany.com", + "password": "thisisabadpassword" +} +``` + +### Sample Request + +```shell +curl \ + --header "Content-Type: application/json" \ + --request POST \ + --data @payload.json \ + https://tfe.company.com/admin/initial-admin-user?token=$(cat iact.txt) +``` + +### Sample Response + +```json +{ + "status": "created", + "token": "aabbccdd.v1.atlas.ddeeffgghhiijjkkllmmnnooppqqrrssttuuvvxxyyzz" +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/automating-the-installer.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/automating-the-installer.mdx new file mode 100644 index 0000000000..4ddc285b9b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/automating-the-installer.mdx @@ -0,0 +1,413 @@ +--- +page_title: Automated Installation - Install and Config - Terraform Enterprise +description: >- + Do an automated installation of Terraform Enterprise. Learn about application and installer settings, and how to wait for Terraform Enterprise to become ready. +--- + +# Automated Terraform Enterprise Installation + +The installation of Terraform Enterprise can be automated for both online and airgapped installs. There are two parts to automating the install: configuring [Replicated](https://help.replicated.com/) -- the platform which runs Terraform Enterprise -- and configuring Terraform Enterprise itself. + +Before starting the install process, you must: + +- prepare an [application settings](#application-settings) file, which defines the settings for the Terraform Enterprise application. +- prepare `/etc/replicated.conf`, which defines the settings for the Replicated installer. +- copy your license file to the instance. +- download the `.airgap` bundle to the instance (Airgapped mode only). + +You may also need to provide additional flags (such as the instance's public and private IP addresses) in order to avoid being prompted for those values when running the installer (which may result in either a failure of the installer or a unbounded delay while waiting for input). + +This document expects that the user is already familiar with how to do a [manual install](/terraform/enterprise/deploy/replicated/install/interactive/installer#installation). + +## Application settings + +This file contains the values you would normally provide in the settings +screen. You need to create this file first since it is referenced in the +`ImportSettingsFrom` property in `/etc/replicated.conf`. + +### Format + +The settings file is JSON formatted. All values must be strings. The following +example shows a possible settings file for a _Mounted Disk_ installation. + +```json +{ + "hostname": { + "value": "terraform.example.com" + }, + "disk_path": { + "value": "/opt/terraform-enterprise" + }, + "enc_password": { + "value": "CHANGEME" + } +} +``` + +> Note: The JSON file must be valid JSON for the install to work, so it's best to validate it before using for an install. + +The easiest way to check the application config is valid JSON would be with `python`, which will be present on most Linux installs: + +``` +$ python -m json.tool settings.json +Expecting property name enclosed in double quotes: line 8 column 5 (char 171) +``` + +After fixing the JSON file, the command will return the valid JSON: + +``` +$ python -m json.tool settings.json +{ + "hostname": { + "value": "terraform.example.com" + }, + "disk_path": { + "value": "/opt/terraform-enterprise" + }, + "enc_password": { + "value": "CHANGEME" + } +} +``` + +### Discovery + +One the easiest ways to get the settings is to [perform a manual install](/terraform/enterprise/deploy/replicated/install/interactive/installer#installation) and configure all the settings the way you want them. Then you can SSH in, request the settings in JSON format and use that file in a future automated install. + +-> **Note**: `replicatedctl` is located at `/usr/local/bin/replicatedctl`. On some operating systems, `/usr/local/bin` is not in the user's `$PATH`. In these cases, either add `/usr/local/bin` to the `$PATH` or refer to `replicatedctl` with the full path. + +To extract the settings as JSON, access the instance via SSH, then run: + +``` +$ replicatedctl app-config export > settings.json +``` + +The following example shows `replicatedctl app-config export` output for an +instance configured in _Mounted Disk_ mode. + +``` +$ replicatedctl app-config export +{ + "aws_access_key_id": {}, + "aws_instance_profile": {}, + "aws_secret_access_key": {}, + "azure_account_key": {}, + "azure_account_name": {}, + "azure_client_id": {}, + "azure_container": {}, + "azure_endpoint": {}, + "azure_use_msi": {}, + "backup_token": {}, + "ca_certs": {}, + "capacity_concurrency": { + "value": "10" + }, + "capacity_cpus": {}, + "capacity_memory": { + "value": "512" + }, + "custom_image_tag": { + "value": "hashicorp/build-worker:now" + }, + "disk_path": { + "value": "/opt/terraform-enterprise" + }, + "enable_active_active": {}, + "enc_password": { + "value": "CHANGEME" + }, + "extern_vault_addr": {}, + "extern_vault_enable": {}, + "extern_vault_namespace": {}, + "extern_vault_path": {}, + "extern_vault_propagate": {}, + "extern_vault_role_id": {}, + "extern_vault_secret_id": {}, + "extern_vault_token_renew": {}, + "extra_no_proxy": {}, + "force_tls": {}, + "gcs_bucket": {}, + "gcs_credentials": {}, + "gcs_project": {}, + "hairpin_addressing": {}, + "hostname": { + "value": "terraform.example.org" + }, + "iact_subnet_list": {}, + "iact_subnet_time_limit": {}, + "log_forwarding_config": {}, + "log_forwarding_enabled": {}, + "metrics_endpoint_enabled": {}, + "metrics_endpoint_port_http": {}, + "metrics_endpoint_port_https": {}, + "pg_dbname": {}, + "pg_extra_params": {}, + "pg_netloc": {}, + "pg_password": {}, + "pg_user": {}, + "placement": {}, + "production_type": { + "value": "disk" + }, + "redis_host": {}, + "redis_pass": {}, + "redis_port": {}, + "redis_use_password_auth": {}, + "redis_use_tls": {}, + "restrict_worker_metadata_access": {}, + "s3_bucket": {}, + "s3_endpoint": {}, + "s3_region": {}, + "s3_sse": {}, + "s3_sse_kms_key_id": {}, + "tbw_image": { + "value": "default_image" + }, + "tls_ciphers": {}, + "tls_vers": { + "value": "tls_1_2_tls_1_3" + } +} +``` + +Note that when you build your own settings file, you do not need to include parameters that do not have `value` keys, such as `extra_no_proxy` in the output above. + +### Available settings + +The settings available to configure your installation are summarized below. It is expected the user will have completed a manual installation first and will already be familiar with the nature of these parameters from the settings screen. + +The following settings apply to every installation: + +- `hostname` — (Required) The hostname you will use to access your installation. + +- `enc_password` — (Required) The [password](/terraform/enterprise/deploy/replicated/install/automated/encryption-password) used to encrypt and decrypt the internally-managed Vault unseal key and root token. Not required only when opting out of internally-managed Vault. + +- `capacity_concurrency` — Number of concurrent plans and applies; defaults to `10`. + +- `capacity_cpus` - The maximum number of CPU cores that a Terraform plan or apply can use on the system; defaults to `0` (unlimited). + +- `capacity_memory` — The maximum amount of memory (in megabytes) that a Terraform plan or apply can use on the system; defaults to `512`. + +- `iact_subnet_list` - A comma-separated list of CIDR masks that configure the ability to retrieve the [IACT](/terraform/enterprise/deploy/replicated/install/automated/automating-initial-user) from outside the host. For example: "10.0.0.0/24, 10.0.1.0/24". If not set, no subnets can retrieve the IACT. + +- `iact_subnet_time_limit` - The time limit that requests from the subnets listed can request the [IACT](/terraform/enterprise/deploy/replicated/install/automated/automating-initial-user), as measured from the instance creation in minutes; defaults to 60. + +- `extra_no_proxy` — (Optional) When configured to use a proxy, a `,` (comma) separated list of hosts to exclude from proxying. Please note that this list does not support whitespace characters. For example: `127.0.0.1,tfe.myapp.com,myco.github.com`. + +- `restrict_worker_metadata_access` - Prevents the environment where Terraform operations are executed from accessing the cloud instance metadata service. This should not be set when Terraform operations rely on using instance metadata (i.e., the instance IAM profile) as part of the Terraform provider configuration. _Note: a bug in Docker version [19.03.3](https://docs.docker.com/engine/release-notes/19.03/#known-issues-1) prevents this setting from working correctly. Operators should avoid using this Docker version when enabling this setting._; Valid values 0 or 1, defaults to 0. + +- `run_pipeline_mode` - Which pipeline to use to perform Terraform runs. Set to `agent` to use Terraform agents. Set to `legacy` to use Terraform Build Worker. Defaults to `agent` unless `custom_image_tag` is non-empty. + +- `hairpin_addressing` - When set, Terraform Enterprise services will direct traffic destined for the installation's FQDN toward the instance's internal IP address. This is useful for cloud environments where HTTP clients running on instances behind a load balancer cannot send requests to the public hostname of that load balancer. Defaults to `false`. + +- `tls_vers` - (Optional) Set to `tls_1_2` to enable only TLS 1.2, or to `tls_1_3` to enable only TLS 1.3. When unset, Terraform Enterprise defaults to both TLS 1.2 and 1.3 (`tls_1_2_tls_1_3`). + +- `tls_ciphers` - (Optional) Set to an OpenSSL [cipher list format](https://www.openssl.org/docs/man1.1.1/man1/ciphers.html) string to enable a custom TLS ciphersuite. When unset, Terraform Enterprise uses a default ciphersuite. + +- `force_tls` - When set, Terraform Enterprise will require all application traffic to use HTTPS by sending a 'Strict-Transport-Security' header value in responses, and marking cookies as secure. A valid, trusted TLS certificate must be installed when this option is set, as browsers will refuse to serve webpages that have an HSTS header set that also serve self-signed or untrusted certificates. + +- `log_forwarding_enabled` - (Optional) Whether or not to enable [log forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging) for Terraform Enterprise. Set to `1` to enable log forwarding and `0` to disable log forwarding. Defaults to `0`. + +- `log_forwarding_config` - (Optional) Valid [log forwarding](/terraform/enterprise/deploy/replicated/monitoring/logging) configuration specifying external destination(s) to forward logs. + +- `metrics_endpoint_enabled` - (Optional) Enable an endpoint to [expose container metrics](/terraform/enterprise/deploy/replicated/monitoring/monitoring#terraform-enterprise-metrics). Defaults to `0`. + +- `metrics_endpoint_port_http` - (Optional) Defines the TCP port on which HTTP metrics requests will be handled. Defaults to `9090`. + +- `metrics_endpoint_port_https` - (Optional) Defines the TCP port on which HTTPS metrics requests will be handled. Defaults to `9091`. + +- `optout_license_reporting` - (Optional) Whether to opt out of Terraform Enterprise license usage data reporting to HashiCorp. Set to `0` to report license usage data to HashiCorp and `1` to disable (or opt out of) reporting usage data. Defaults to `0`. + +- `ca_certs` — (Optional) Custom certificate authority (CA) bundle. JSON does not allow raw newline characters, so replace any newlines + in the data with `\n`. For instance: + + ``` + --- X509 CERT --- + aabbccddeeff + --- X509 CERT --- + ``` + + would become + + ``` + --- X509 CERT ---\naabbccddeeff\n--- X509 CERT ---\n + ``` + +- `extern_vault_enable` — (Optional) Indicate if an external Vault cluster is being used. Set to `1` if so. + + - These variables are only used if `extern_vault_enable` is set to `1`. + - `extern_vault_addr` — (Required) URL of external Vault cluster. + - `extern_vault_role_id` — (Required) AppRole RoleId to use to authenticate with the Vault cluster. + - `extern_vault_secret_id` — (Required) AppRole SecretId to use to authenticate with the Vault cluster. + - `extern_vault_path` — (Optional) Path on the Vault server for the AppRole auth. Defaults to `auth/approle`. + - `extern_vault_token_renew` — (Optional) How often (in seconds) to renew the Vault token. Defaults to `3600`. + - `extern_vault_namespace` — (Optional) The Vault namespace to use. Leave blank to use the default namespace. When running v202205-1, be aware of this [known issue](/terraform/enterprise/releases/2022/v202205-1#known-issues). + +- `vault_path` — (Optional) Path on the host system to store the vault files. If `extern_vault_enable` is set, this has no effect. + +- `vault_store_snapshot` — (Optional) Indicate if the vault files should be stored in snapshots. Set to `0` if not. Defaults to `1`. + +- `production_type` — Either `external` or `disk`. Defaults to `disk`. + +If you have chosen `disk` for `production_type`, `disk_path` is required: + +- `disk_path` — Path on instance to persistent storage. +- `pg_password` — The password for the internal PostgreSQL access. The password will be auto-generated for each installation if not provided. + +If you want to use a [custom image](/terraform/enterprise/deploy/replicated/install/interactive/installer#custom-image), the following settings apply: + +For a [legacy custom image](/terraform/enterprise/deploy/replicated/install/interactive/installer#legacy): + +- `tbw_image` - Set this to `custom_image` if you want to use a legacy custom image. Defaults to `default_image`. +- `custom_image_tag` - The legacy custom image to use (e.g. `registry.example.com/example/terraform-enterprise-worker:custom-tag`). Leave blank to use the built-in default image. Defaults to `""`. + +For an [agent custom image](/terraform/enterprise/deploy/replicated/install/interactive/installer#agent): + +- `custom_agent_image_tag` - The agent custom image to use (e.g. `registry.example.com/example/tfc-agent:custom-tag`). Leave blank to use the built-in default image. Defaults to `""`. + +If you have chosen `external` for `production_type`, the following settings apply: + +- `pg_user` — (Required) PostgreSQL user to connect as. +- `pg_password` — (Required) The password for the PostgreSQL user. +- `pg_netloc` — (Required) The hostname and port of the target PostgreSQL server, in the format `hostname:port`. +- `pg_dbname` — (Required) The database name. +- `pg_extra_params` — (Optional) Parameter keywords of the form `param1=value1¶m2=value2` to support additional options that may be necessary for your specific PostgreSQL server. Allowed values are [documented on the PostgreSQL site](https://www.postgresql.org/docs/12/libpq-connect.html#LIBPQ-PARAMKEYWORDS). An additional restriction on the `sslmode` parameter is that only the `require`, `verify-full`, `verify-ca`, and `disable` values are allowed. + +Select which placement will be used for blob storage: S3, Azure, or GCS. Based on this value, you only need to provide one set of the following variables. + +- `placement` — (Required) Set to `placement_s3` for S3, `placement_azure` for Azure, or `placement_gcs` for GCS. + +For S3 (or S3-compatible storage providers): + +- `aws_instance_profile` (Optional) When set, use credentials from the AWS instance profile. Set to 1 to use the instance profile. Defaults to 0. If selected, `aws_access_key_id` and `aws_secret_access_key` are not required. +- `aws_access_key_id` — (Required unless `aws_instance_profile` is set) AWS access key ID for S3 bucket access. To use AWS instance profiles for this information, set it to `""`. +- `aws_secret_access_key` — (Required unless `aws_instance_profile` is set) AWS secret access key for S3 bucket access. To use AWS instance profiles for this information, set it to `""`. +- `s3_endpoint` — (Optional) Endpoint URL (hostname only or fully qualified URI). Usually only needed if using a VPC endpoint or an S3-compatible storage provider. +- `s3_bucket` — (Required) The S3 bucket where resources will be stored. +- `s3_region` — (Required) The region where the S3 bucket exists. +- `s3_sse` — (Optional) Enables server-side encryption of objects in S3; if provided, must be set to `aws:kms`. +- `s3_sse_kms_key_id` — (Optional) An optional KMS key for use when S3 server-side encryption is enabled. + +As of the `v202103-1` release, Terraform Enterprise supports using AWS IMDSv2 when using the instance profile to obtain credentials to connect to S3 object storage. + +For Azure: + +- `azure_account_name` — (Required) The Azure storage account name. +- `azure_container` — (Required) The Azure storage container name. +- `azure_endpoint` — (Optional) The Azure storage account endpoint. Leave blank to use the default Blob Storage endpoint. +- `azure_account_key` — (Optional) The storage account key used for authentication. Ignored when `azure_use_msi` is `1`. +- `azure_client_id` — (Optional) The client ID of the user-assigned managed identity used for authentication. Leave blank to use the system-assigned managed identity. Only used when `azure_use_msi` is `1`. +- `azure_use_msi` — (Optional) Use a managed identity for authentication instead of a storage account key. Set to `1` to enable and `0` to disable. Defaults to `0`. + +For GCS: + +- `gcs_project` — (Required) The GCP project where the bucket resides. +- `gcs_bucket` — (Required) The storage bucket name. +- `gcs_credentials` — (Optional) JSON blob containing the GCP credentials document. If this value is not present or `{}`, then GCP attempts to [authenticate with the service account](https://cloud.google.com/docs/authentication/production) attached to the instance. **Note:** This is a string, so ensure values are properly escaped. + +## Installer settings + +### Online + +The following is an example `/etc/replicated.conf` suitable for an automated online install using a certificate trusted by a public or private CA. `ImportSettingsFrom` must be the full path to the application settings file. You also need to provide the full path to your license file in `LicenseFileLocation`. + +See the full set of configuration parameters in the [Replicated documentation](https://help.replicated.com/docs/native/customer-installations/automating/#configure-replicated-automatically). + +```json +{ + "DaemonAuthenticationType": "password", + "DaemonAuthenticationPassword": "your-password-here", + "TlsBootstrapType": "server-path", + "TlsBootstrapHostname": "server.company.com", + "TlsBootstrapCert": "/etc/server.crt", + "TlsBootstrapKey": "/etc/server.key", + "BypassPreflightChecks": true, + "ImportSettingsFrom": "/path/to/settings.json", + "LicenseFileLocation": "/path/to/license.rli" +} +``` + +#### Invoking the online installation script + +Once `/etc/replicated.conf` has been created, you can retrieve and execute the install script as `root`: + +```bash +curl -o install.sh https://install.terraform.io/ptfe/stable +bash ./install.sh \ + no-proxy \ + private-address=1.2.3.4 \ + public-address=5.6.7.8 +``` + +We recommend you always supply the `private-address` and `public-address` flags to the installer. If the virtual machine instance will not have its own separate public IP address (i.e. you are using a load balancer and a private subnet), you should provide the private IP address for both flags. + +The installer will prompt you for these flags if it cannot determine them automatically. If you use `cloud-init` or another non-interactive method to run the installer, you will see this prompt in the log output, but the installer will continue to run. If the installer is unable to determine the IP addresses and you do not provide them, the installation will appear to be successful, but Terraform Enterprise will have degraded functionality. For example, you may see `Internal error: SIW-001` when importing modules to the private registry or notice that the Archivist and Vault containers are unhealthy when you run the `tfe-admin health-check` command. + +### Airgapped + +The following is an example `/etc/replicated.conf` suitable for an automated airgapped install, which builds on the online example above. Note the addition of `LicenseBootstrapAirgapPackagePath`, which is a path to the `.airgap` bundle on the instance. + +```json +{ + "DaemonAuthenticationType": "password", + "DaemonAuthenticationPassword": "your-password-here", + "TlsBootstrapType": "server-path", + "TlsBootstrapHostname": "server.company.com", + "TlsBootstrapCert": "/etc/server.crt", + "TlsBootstrapKey": "/etc/server.key", + "BypassPreflightChecks": true, + "ImportSettingsFrom": "/path/to/settings.json", + "LicenseFileLocation": "/path/to/license.rli", + "LicenseBootstrapAirgapPackagePath": "/path/to/bundle.airgap" +} +``` + +#### Invoking the airgap installation script + +Following on from the [manual airgapped install](/terraform/enterprise/deploy/replicated/install/interactive/installer#run-the-installer-airgapped) steps, you must also have the installer bootstrapper already on the instance. For illustrative purposes, it is assumed the installer bootstrapper has been unarchived in `/tmp`. + +Once `/etc/replicated.conf` has been created, you can now execute the install script as `root`: + +```bash +cd /tmp +./install.sh \ + airgap \ + no-proxy \ + private-address=1.2.3.4 \ + public-address=5.6.7.8 +``` + +-> **Note**: The `./install.sh` script must be executed from the directory in which it is placed. + +## Waiting for Terraform Enterprise to become ready + +Once the installer finishes, you may poll the `/_health_check` endpoint until a `200` is returned by the application, indicating that it is fully started: + +```bash +while ! curl -ksfS --connect-timeout 5 https://tfe.example.com/_health_check; do + sleep 5 +done +``` + +## If the installation does not appear to be configured correctly + +If the installation script (`install.sh`) exits successfully, but the Replicated web UI prompts for additional configuration rather than skipping that step, it's likely that the supplied configuration files were not applied during installation. + +- Verify the locations and permissions of the files. The Replicated configuration file should be placed in `/etc/replicated.conf`, and the application settings file should be placed in the path specified in the Replicated configuration file. The permissions of both files should be `600` if owned by the `replicated` user, or `644`. +- Run a JSON validator on the files to check their validity. + +After resolving any issues with file validity or permissions, run the following commands to reload your configuration: + +~> **Important:** These commands are only for fixing a new installation. Do not run these commands on an existing installation, as they will destroy important data. + +```bash +sudo systemctl stop replicated replicated-ui replicated-operator +sudo rm -rf /var/lib/replicated +sudo systemctl start replicated replicated-ui replicated-operator +``` + +## References + +- [Replicated installer flags](https://help.replicated.com/docs/native/customer-installations/installing-via-script/#flags) +- [`/etc/replicated.conf`](https://help.replicated.com/docs/native/customer-installations/automating/#configure-replicated-automatically) +- [application settings](https://help.replicated.com/docs/native/customer-installations/automating/#configure-replicated-automatically) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/encryption-password.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/encryption-password.mdx new file mode 100644 index 0000000000..d8d477ec2d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/automated/encryption-password.mdx @@ -0,0 +1,51 @@ +--- +page_title: Encryption Password - Install and Config - Terraform Enterprise +description: >- + The Terraform Enterprise encryption password protects the internally-managed Vault unseal key and root token. Learn how to specify and retrieve the encryption password. +--- + +# Terraform Enterprise Encryption Password + +When using internally-managed Vault, Terraform Enterprise requires that the operator specify a password that will be +used to to encrypt and decrypt the internally-managed Vault unseal key and root token. This password is called the +"encryption password". Please be sure to retain this value as it will be needed in the event of a re-installation. + +The encryption password is used to protect the internally-managed Vault unseal key and root token with a password +provided by the operator. It allows Terraform Enterprise to securely store the Vault unseal key and root token in +PostgreSQL, which means that Vault is only dependent on the encryption password itself and the data in PostgreSQL. + +## Specifying the Encryption Password + +### Manual Installation + +For manual installations, the encryption password can be specified via the "Encryption Password" field: + +![User interface for encryption password field.](/img/docs/enc-password-manual-install.png) + +### Automated Installation + +For automated installations, the encryption password can be specified via the `enc_password` setting in the +[application settings JSON file](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#available-settings): + +```json +{ + "hostname": { + "value": "terraform.example.com" + }, + "installation_type": { + "value": "poc" + }, + "enc_password": { + "value": "CHANGEME" + } +} +``` + +## Retrieving the Encryption Password + +To retrieve the encryption password that Terraform Enterprise is currently configured to use, connect to your Terraform +Enterprise instance and execute the following: + +``` +replicatedctl app-config export --template '{{.enc_password.Value}}' +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/interactive/config.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/interactive/config.mdx new file mode 100644 index 0000000000..0d321ca813 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/interactive/config.mdx @@ -0,0 +1,54 @@ +--- +page_title: Configuration - Install and Config - Terraform Enterprise +description: >- + Use a web browser to configure Terraform Enterprise after installation. Learn how to create an administrator with the UI or HTTP API, and create your first organization. +--- + +# Terraform Enterprise Configuration + +After you have completed the installation process you will need to create an +admin user. When the admin user creation has been completed you will +be able to create your first organizations and users and enable the enterprise +features for those accounts. + +~> **Note:** If you are performing an upgrade or restore for an existing +installation you _do not_ need to follow these steps. If your upgraded or +restored installation does not function without the steps below then it was not +correctly restored from backup. Please contact HashiCorp for help. + +## System Configuration + +In all examples below, be sure to replace "``" with the hostname +of your Terraform Enterprise instance. + +Navigate to `https://:8800/` in your browser. You will +be presented with the installer dashboard. + +### Creating an Administrator (UI) + +After clicking on the "Open", right below the "Stop Now" button, you will +be brought to a page asking you to create the first Terraform Enterprise administrator account. +You will be able to create additional administrators once you log in. + +### Creating an Administrator (API) + +The initial Admin user can be created via a special API. Customers can use this +method to more easily perform automated installations of Terraform Enterprise. + +The API and usage documents are under [Automating Initial User](/terraform/enterprise/deploy/replicated/install/automated/automating-initial-user). + +### Creating an organization + +The next step will create the first organization. + +After this is done, you can either continue with the creation of a new workspace, +choose to configure other aspects of Terraform Enterprise, or add more users. + +## Success! + +You have successfully configured the installation and configuration steps that +are specific to Terraform Enterprise! You can now configure SMTP +(`https:///app/admin/smtp/`), Twilio (`https:///app/admin/twillio`), +SAML (`https:///app/admin/saml`), or follow the +[Get Started - HCP Terraform](/terraform/tutorials/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) +tutorials to start using the software. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/interactive/installer.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/interactive/installer.mdx new file mode 100644 index 0000000000..f0714d5104 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/interactive/installer.mdx @@ -0,0 +1,372 @@ +--- +page_title: Interactive Installation - Install and Config - Terraform Enterprise +description: >- + Use the Terraform Enterprise installer on a customer-controlled machine. Learn about proxy usage, TLS configuration, using a custom container image, operational mode, installation, and configuration. +--- + +# Interactive Terraform Enterprise Installation + +## Delivery + +This document outlines the procedure for using the Terraform Enterprise +installer to set up Terraform Enterprise on a customer-controlled machine. + +-> **Important:** Before you begin, consult the [Pre-Install Checklist](/terraform/enterprise/deploy/replicated/install/pre-install-checklist) for prerequisites. You'll need to prepare data files and a Linux instance. + +## Proxy Usage + +If your installation requires using a proxy server, you will be asked for the proxy server information when you first +run the installer via `ssh`. This proxy server will be used for all outbound HTTP and HTTPS connections. + +Optionally, if you're running the installer script in an automated manner, you can pass a `http-proxy` flag to set +the address of the proxy. For example: + +``` +./install.sh http-proxy=http://internal.mycompany.com:8080 +``` + +### Proxy Exclusions (NO_PROXY) + +If certain hostnames should not use the proxy and the instance should connect directly to them (for instance, for S3), then you can pass an additional option to provide a list of domains: + +``` +./install.sh additional-no-proxy=s3.amazonaws.com,internal-vcs.mycompany.com,example.com +``` + +Passing this option to the installation script is particularly useful if the hostnames that should not use the proxy include services that the instance needs to be able to reach during installation, such as S3. Alternately, if the only hosts you need to add are those that are not used during installation, such as a private VCS instance, you can provide these hosts after initial installation is complete, in the settings tab in your dashboard (available on port 8800 under `/console/settings`). + +### Reconfiguring the Proxy + +To change the proxy settings after installation, use the Console settings page, accessed from the dashboard on port 8800 under `/console/settings`. + +![Terraform Enterprise Console Settings](/img/docs/tfe-console-settings.png) + +On the Console Settings page, there is a section for HTTP Proxy: + +![Terraform Enterprise HTTP Proxy Settings](/img/docs/tfe-http-proxy.png) + +This change updates the proxy settings for the Terraform Enterprise application services. To update the proxy settings for the installer (for example, to handle configuration tests correctly), additional steps are necessary: + +1. Locate the Replicated configuration files on the instance under either `/etc/sysconfig/` or `/etc/default`: `replicated` and `replicated-operator`. +1. Open the files for editing. On the line that includes `REPLICATED_OPTS` for `replicated` or `REPLICATED_OPERATOR_OPTS` for `replicated-operator`, add `-e HTTP_PROXY= -e NO_PROXY=` to the existing command options. The list of `no_proxy` hosts is a comma-separated list with no spaces, and should include following addresses `127.0.0.1,,,` but not limited to. +1. Docker also needs to be able to communicate to endpoints with the same rules of proxy settings as `replicated` and `replicated-operator`, the steps 1-6 of this [document](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) are required. + `NOTE: Please take precautions on application outage when applying configuration change, i.e. wait for all runs to finish, prevent new runs to trigger` +1. Restart the Replicated services following [the instructions for your distribution](https://help.replicated.com/docs/native/customer-installations/installing-via-script/#restarting-replicated). + +### Proxy and Service Discovery Process + +Unless the execution mode of a workspace is set to "local", Terraform Enterprise performs [remote operations](/terraform/enterprise/run/remote-operations), running Terraform in its own worker VMs. + +When running within Terraform Enterprise's worker VMs, Terraform uses [service discovery](/terraform/internals/remote-service-discovery) to find the Terraform Enterprise service itself. Depending on your infrastructure setup, you may need to tell Terraform Enterprise not to access its own hostname via the proxy, so that Terraform can communicate with the Terraform Enterprise services. + +To do this, add Terraform Enterprise's fully qualified hostname to the **Proxy Bypass** setting in Terraform Enterprise's dashboard. The proxy bypass setting can be found on port **8800** on the path `/settings`. + +![Terraform Enterprise Proxy Bypass](/img/docs/tfe-proxy-bypass.png) + +Save the configuration using the **Save** button at the bottom of the page. Once configuration has been saved, please proceed to restart the application. + +You can use the equivalent setting, [extra_no_proxy](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#available-settings), to automate this step. + +The Terraform CLI performs a TLS handshake with Terraform Enterprise during service discovery, and will need access to the Certificate Authority that Terraform Enterprise uses. + +Either add the CA to the [CA Custom Bundle](#certificate-authority-ca-bundle) configuration so that Terraform Enterprise will make the CA available in the worker container, or, if a [custom worker image](#custom-agent-image) is configured, add the CA directly to its certificate file (located at `/etc/ssl/certs/ca-certificates.crt`). + +## TLS Configuration + +There are two sections for TLS configuration; the "TLS Key & Cert" section and the "SSL/TLS Configuration" section. + +### TLS Key & Cert + +The "TLS Key & Cert" section is where the TLS certificate and private key can be configured to allow HTTPS connections to Terraform Enterprise. The TLS certificate and private key files can be self-signed, located in a path on the server, or uploaded. Both the TLS certificate and private key files must be PEM-encoded. The TLS certificate file can contain a full chain of TLS certificates if necessary. + +For convenience, a brand new Terraform Enterprise installation may prompt for these settings after the initial setup. You can provide a key and certificate immediately, or use a self-signed certificate to begin with and change the settings later. + +![Installer TLS Key and Cert](/img/docs/tls-installer.png) + +For an existing installation, these settings can be found in the Replicated console on port 8800. Click on the gear icon in the top right corner, click "Console Settings", and scroll to the "TLS Key & Cert" section. + +The key and certificate settings can be one of three values, each of which are detailed below. + +#### Self-signed (generated) + +When the "Self-signed (generated)" radio button is selected, a self-signed TLS certificate and private key will be automatically generated. An example screenshot is below: + +![Self-signed TLS Key and Cert](/img/docs/tls-self-signed.png) + +#### Server path + +When the "Server path" radio button is selected, the TLS certificate and private key will be read from the specified file paths on the server. An example screenshot is below: + +![Server Path TLS Key and Cert](/img/docs/tls-server-path.png) + +#### Upload files + +When the "Upload file" radio button is selected, the TLS certificate and private key must be uploaded. An example screenshot is below: + +![Upload File TLS Key and Cert](/img/docs/tls-upload.png) + +~> **Note:** Changes to the key and certificate settings require a restart of the Terraform Enterprise application. + +### Certificate Authority (CA) Bundle + +Terraform Enterprise needs to be able to access all services that it integrates with, such as VCS providers or database servers. +Because it typically accesses them via SSL/TLS, it is critical that the certificates used by any service +that Terraform Enterprise integrates with are trusted by Terraform Enterprise. + +This section is used to allow Terraform Enterprise to connect to services that use SSL/TLS certificates issued by private CAs. +It allows multiple certificates to be specified as trusted, and should contain all certificates that Terraform Enterprise +should trust when presented with them from itself or another application. + +A collection of certificates for trusted issuers is known as a `Certificate Authority (CA) Bundle`. +All certificates in the certificate signing chain, meaning the root certificate and any intermediate certificates, +must be included here. These multiple certificates are listed one after another in text format. + +~> **Note:** If Terraform Enterprise is configured with a SSL key and certificate issued against a private CA, +the certificate chain for that CA must be included here as well. This allows the instance +to query itself. + +Certificates must be formatted using PEM encoding, that is, as text. For example: + +``` +-----BEGIN CERTIFICATE----- +MIIFtTCCA52gAwIBAgIIYY3HhjsBggUwDQYJKoZIhvcNAQEFBQAwRDEWMBQGA1UE +AwwNQUNFRElDT00gUm9vdDEMMAoGA1UECwwDUEtJMQ8wDQYDVQQKDAZFRElDT00x +CzAJBgNVBAYTAkVTMB4XDTA4MDQxODE2MjQyMloXDTI4MDQxMzE2MjQyMlowRDEW +MBQGA1UEAwwNQUNFRElDT00gUm9vdDEMMAoGA1UECwwDUEtJMQ8wDQYDVQQKDAZF +.... +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +MIIB5zCCAY6gAwIBAgIUNJADaMM+URJrPMdoIeeAs9/CEt4wCgYIKoZIzj0EAwIw +UjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1TYW4gRnJhbmNp +c2NvMR4wHAYDVQQDExVoYXNoaWNvcnAuZW5naW5lZXJpbmcwHhcNMTgwMjI4MDYx +.... +-----END CERTIFICATE----- +``` + +The user interface to upload these certificates looks like this: + +![Terraform Enterprise Certificate Authority User Interface](/img/docs/tls-ca.png) + +#### TLS Versions + +As of version 201902-01, TLS versions 1.0 and 1.1 are no longer supported in Terraform Enterprise. Your options now include TLS v1.2 and TLS v1.3: + +![Terraform Enterprise TLS Versions User Interface](/img/docs/tls-versions.png) + +#### TLS Ciphersuites + +Terraform Enterprise uses the `HIGH:!aNULL:!MD5` ciphersuites by default. You can also provide a custom ciphersuite if necessary. + +![Terraform Enterprise TLS Ciphersuite User Interface](/img/docs/tls-ciphers.png) + +(This value must be defined in the OpenSSL [cipher list format](https://www.openssl.org/docs/man1.1.1/man1/ciphers.html) + +#### Force TLS with HSTS + +Terraform Enterprise may be configured to force TLS via the enabling of HTTP Strict Transport Security: + +![Terraform Enterprise TLS HSTS User Interface](/img/docs/tls-hsts.png) + +## Custom Image + +@include "replicated-and-fdo/requirements/custom-image.mdx" + +### Legacy + +Build your custom image using either the Ubuntu or Red Hat `Dockerfile` below. +Then update the `custom_image_tag` setting with your image (e.g. +`registry.example.com/example/terraform-enterprise-worker:custom-tag`). + +![The `custom_image_tag` setting in the user interface.](/img/docs/tfe_console-custom_image_tag.png) + +#### Requirements + +- The base image must be `ubuntu:bionic` or an [offical Red Hat Enterprise Linux 7 image](https://catalog.redhat.com/software/containers/search?p=1&rows=60&vendor_name=Red%20Hat&build_categories_list=Scratch%20image&product_listings_names=Red%20Hat%20Universal%20Base%20Image%207) + (e.g. `registry.access.redhat.com/ubi7/ubi-minimal:latest`). +- The image must exist on the Terraform Enterprise host. You can add it by + running `docker pull` from a local registry or any other similar method. +- The software packages defined in the examples below must be installed on the + image. +- All necessary CA certificates must be added to the container's CA bundle. The + CA certificates configured in the [CA Bundle settings](#certificate-authority-ca-bundle) + will not be automatically added to this image at runtime. See the examples + below for more details. +- Terraform must not be installed on the image. Terraform Enterprise installs + Terraform at runtime. + +#### Ubuntu + +```Dockerfile +FROM ubuntu:bionic + +# Install required software for Terraform Enterprise. +RUN DEBIAN_FRONTEND=noninteractive && \ + apt-get update && \ + apt-get install -y --no-install-recommends awscli ca-certificates curl daemontools git-core iproute2 netcat-openbsd openssh-client psmisc redis-tools ssh sudo unzip wget + +# Include all necessary CA certificates. +ADD example-root-ca.crt /usr/local/share/ca-certificates/ +ADD example-intermediate-ca.crt /usr/local/share/ca-certificates/ +RUN update-ca-certificates +``` + +#### Red Hat Enterprise Linux 7 + +In addition to the packages that yum installs, curl installs the envdir tool +Python port because it is a dependency of the Terraform Build Worker service. +If the envdir tool is not installed on the alternative worker image, Terraform +runs will fail within Terraform Enterprise. + +```docker +FROM registry.access.redhat.com/ubi7/ubi-minimal:latest + +# Update installed packages and clear cache. +RUN microdnf --assumeyes update && \ + rm --recursive --force /var/cache/yum + +# Install required software for Terraform Enterprise. +RUN microdnf --assumeyes install curl git iproute nmap-ncat openssh openssl psmisc sudo unzip wget && \ + microdnf clean all && \ + curl --location --output /usr/local/bin/envdir https://github.com/jezdez/envdir/releases/download/0.7/envdir-0.7.pyz && \ + chmod +x /usr/local/bin/envdir + +# Include all necessary CA certificates. +ADD example-root-ca.crt /usr/share/pki/ca-trust-source/anchors +ADD example-intermediate-ca.crt /usr/share/pki/ca-trust-source/anchors +RUN update-ca-trust +``` + +#### Executing Custom Scripts + +The custom image supports executing custom scripts during different points of a +run. + +-> **Note:** Custom scripts are for the `legacy` run pipeline mode only. As of Terraform Enterprise v202302-1, the default run pipeline mode is `agent`. If you wish to use a custom image for the `legacy` run pipeline mode, you must [build a legacy custom image](#legacy). See the [release notes](/terraform/enterprise/releases/2023/v202302-1) and the [worker to agent migration guide](/terraform/enterprise/deploy/replicated/administration/infrastructure/worker-to-agent-migration) for more information about the run pipeline mode change. Support for the `legacy` run pipeline mode and legacy custom images will end in v202305-1. + +##### Initialize Script + +To execute an initialize script, ensure your worker image contains an executable shell script at +`/usr/local/bin/init_custom_worker.sh`. This script, and all commands it invokes, will be executed before a Terraform +Enterprise run executes `terraform init`. This initialize script will be executed during both plans and applies. + +Example `Dockerfile` snippet for adding an initialize script: + +``` +ADD init_custom_worker.sh /usr/local/bin/init_custom_worker.sh +``` + +##### Finalize Script + +To execute a finalize script, ensure your worker image contains an executable shell script at +`/usr/local/bin/finalize_custom_worker.sh`. This script, and all commands it invokes, will be executed after a Terraform +Enterprise run finishes executing `terraform plan` or `terraform apply`. This finalize script will be executed during +both plans and applies. + +Example `Dockerfile` snippet for adding a finalize script: + +``` +ADD finalize_custom_worker.sh /usr/local/bin/finalize_custom_worker.sh +``` + +## Operational Mode Decision + +Terraform Enterprise can store its state in a few different ways, and you'll +need to decide which works best for your installation. Each option has a +different approach to +[recovering from failures](/terraform/enterprise/deploy/replicated/administration/infrastructure/automated-recovery). +The mode should be selected based on your organization's needs. See +[Pre-Install Checklist: Operational Mode Decision](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operational-mode-decision) +for more details. + +## Installation + +The installer can run in two modes, Online or Airgapped. Each of these modes has a different way of executing the installer, but the result is the same. + +~> **Note:** After running the installation script, the remainder of the installation is done through a browser using the installer dashboard on port 8800 of the Terraform Enterprise instance. To complete the installation, you must be able to connect to that port via HTTPS. The installer uses an internal CA to issue bootstrap certificates, so you will see a security warning when first connecting, and you'll need to proceed with the connection anyway. + +### Run the Installer - Online + +If your instance can access the Internet, use the Online install mode. + +1. From a shell on your instance: + - To execute the installer directly, run `curl https://install.terraform.io/ptfe/stable | sudo bash`. + - To inspect the script locally before running, run `curl https://install.terraform.io/ptfe/stable > install.sh` and, once you are satisfied with the script's content, execute it with `sudo bash install.sh`. + - RedHat Enterprise Linux requires Docker to be pre-installed. As such, execute the installer script using `sudo bash install.sh no-docker` to prevent the installer script from automatically installing Docker. +1. The installation will take a few minutes and you'll be presented with a message + about how and where to access the rest of the setup via the web. This will be + `https://:8800`. + - You will see a security warning when first connecting. This is expected and you'll need + to proceed with the connection anyway. + +### Run the Installer - Airgapped + +If the instance cannot reach the Internet, follow these steps to begin an Airgapped installation. + +#### Prepare the Instance + +1. Airgap installations require Docker to be pre-installed. Double-check that your instance has a supported version of Docker (see [Pre-Install Checklist: Software Requirements](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#software-requirements) for details). +1. Download the `.airgap` file using the information given to you in your setup email and place that file somewhere on the the instance. + - If you use are using `wget` to download the file, be sure to use `wget --content-disposition ""` so the downloaded file gets the correct extension. + - The url generated for the .airgap file is only valid for a short time, so you may wish to download the file and upload it to your own artifacts repository. +1. [Download the installer bootstrapper](https://install.terraform.io/airgap/latest.tar.gz) and put it into its own directory on the instance (e.g. `/opt/tfe-installer/`) + - The downloaded file may be named `replicated.tar.gz` or `latest.tar.gz`. We'll refer to it as `replicated.tar.gz` for the rest of this page. + +#### Execute the Installer + +From a shell on your instance, in the directory where you placed the `replicated.tar.gz` installer bootstrapper: + +1. Run `tar xzf replicated.tar.gz` +1. Run `sudo ./install.sh airgap` +1. When asked, select the interface of the primary private network interface used to access the instance. +1. The software will take a few minutes and you'll be presented with a message about how and where to access the rest of the setup via the web. This will be `https://:8800`. + - You will see a security warning when first connecting. This is expected and you'll need + to proceed with the connection anyway. + +### Continue Installation In Browser + +1. Configure the hostname and the SSL certificate. +1. Upload the license file provided to you in your setup email. +1. Indicate whether you're doing an Online or Airgapped installation. Choose Online if + you're not sure. + - If you are doing an Airgapped install, provide the path on the the instance + to the `.airgap` file that you downloaded using the initial instructions in + your setup email. +1. Secure access to the installer dashboard. We recommend at least setting up the + simple password authentication. If you're so inclined, LDAP authentication can also be + configured. +1. The system will now perform a set of pre-flight checks on the instance and + the configuration up to this point and indicate any failures. You can either fix the issues + and re-run the checks, or ignore the warnings and proceed. If the system is running behind a proxy and is unable to connect to `releases.hashicorp.com:443`, it is likely safe to proceed; this check does not currently use the proxy. For any other issues, if you proceed despite the warnings, you are assuming the support responsibility. +1. Set an encryption password used to encrypt the sensitive information at rest. The default value is auto-generated, + but we strongly suggest you create your own password. Be sure to retain the value, because you will need to use this + password to restore access to the data in the event of a reinstall. See [Encryption Password](/terraform/enterprise/deploy/replicated/install/automated/encryption-password) for more information. +1. Configure the operational mode for this installation. See + [Pre-Install Checklist: Operational Modes](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operational-mode-decision) for information on what the different values are. Ensure that you've met the relevant pre-install requirements for the mode you chose. +1. _Optional:_ Adjust the concurrent capacity of the instance. This should + only be used if the hardware provides more resources than the baseline + configuration and you wish to increase the work that the instance does + concurrently. This setting should be adjusted with care as setting it too + high can result in an very unresponsive instance. +1. _Optional:_ Provide the text version of a certificate (or certificates) that will be added to the trusted + list for the product. This is used when services the product communicates with do not use + globally trusted certificates but rather a private Certificate Authority (CA). This is typically + used when Terraform Enterprise uses a private certificate (it must trust itself) or a + VCS provider uses a private CA. +1. _Optional:_ Adjust the path used to store the vault files that are used to encrypt + sensitive data. This is a path on the host system, which allows you + to store these files outside of the product to enhance security. Additionally, + you can configure the system not to store the vault files within any snapshots, + giving you full custody of these files. These files will need to be provided before + any snapshot restore process is performed, and should be placed into the path configured. +1. _Optional:_ Configure the product to use an externally managed Vault cluster. + See [Externally Managed Vault Cluster](/terraform/enterprise/deploy/replicated/install/vault) for details about the required Vault configuration before using this option. + +### Finish Bootstrapping + +Once configured, the software will finish downloading. When it’s ready, the UI +will indicate so and there will be an Open link to click to access the Terraform Enterprise UI. + +## Configuration + +After completing a new install you should head to the [configuration +page](/terraform/enterprise/deploy/replicated/install/interactive/config) to continue setting up Terraform Enterprise. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/operation-modes.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/operation-modes.mdx new file mode 100644 index 0000000000..604c95d0d8 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/operation-modes.mdx @@ -0,0 +1,106 @@ +--- +page_title: Operational Modes - Terraform Enterprise +description: Learn about the different operational modes of Terraform Enterprise. +--- + +# Terraform Enterprise Operational Modes + +You must choose an operational mode before you install and deploy Terraform +Enterprise. Each operational mode changes where Terraform Enterprise stores its +data. + +## Terraform Enterprise Data + +Terraform Enterprise uses the following types of data. + +- **PostgreSQL Database:** - Stateful Terraform Enterprise application data. This includes workspace settings, organization settings, run information, and user information. + +- **Object Storage:** - Artifacts that Terraform Enterprise produces during operation. This includes state files, plan files, run logs, configuration versions, etc. + +- **Vault:** - Encryption keys that encrypt and decrypt objects within object storage. + +- **Redis:** - Application coordination and data caching. + +- **Configuration:** - Configuration settings. This includes the hostname, object storage credentials, database credentials, concurrency settings, etc. + +## Operational Modes + +The following table summarizes where each Terraform Enterprise operational mode +stores each type of application data. + +| Operational Mode | PostgreSQL Database | Object Storage | Vault | Redis | Configuration | +| --------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------- | +| [External Services](#external-services) | External, user-managed PostgreSQL database | External, user-managed object storage location | PostgreSQL Database unless using [External Vault](/terraform/enterprise/deploy/replicated/install/vault) | Docker volume on the instance | Docker volume on the instance | +| [Active/Active](#active-active) | External, user-managed PostgreSQL database | External, user-managed object storage location | PostgreSQL Database unless using [External Vault](/terraform/enterprise/deploy/replicated/install/vault) | External, user-managed Redis instance | Docker volume on the instance | +| [Mounted Disk](#mounted-disk) | Directory on the instance backed by user-managed persistent storage | Directory on the instance backed by user-managed persisent storage | PostgreSQL Database unless using [External Vault](/terraform/enterprise/deploy/replicated/install/vault) | Docker volume on the instance | Docker volume on the instance | + +## External Services + +The External Services operational mode stores the PostgreSQL Database and +Object Storage data on an external PostgreSQL server and S3-compatible object +storage. This allows you to backup, restore, and scale the PostgreSQL Database +or Object Storage independently of the Terraform Enterprise instance. + +You are responsible for providing and maintaining the external PostgreSQL +server and S3-compatible object storage. + +External Services stores configuration data on a Docker volume on the instance. +Use `replicatedctl app-config export` to retrieve the configuration data. + +### When to Use External Services + +We recommend using External Services in the following use cases: + +- Your environment has an external PostgreSQL server and S3-compatible object storage. +- You have experience managing a PostgreSQL server such as Amazon RDS for PostgreSQL, Google Cloud SQL for PostgreSQL, Azure Database for PostgreSQL, etc. +- You have experience managing an S3-compatible object storage location such as AWS S3, Azure Blob Storage, Google Cloud Storage, MinIO, etc. +- You want to use native backup and restore features provided by the external PostgreSQL server and S3-compatible object storage. + +## Active/Active + +The Active/Active operational mode stores the PostgreSQL Database and Object +Storage data on an external PostgreSQL server and S3-compatible object storage. +This allows you to backup, restore, and scale the PostgreSQL Database or Object +Storage independently of the Terraform Enterprise instance. Additionally, +Active/Active stores Redis data in an external Redis instance, allowing you +to use multiple instances of Terraform Enterprise in an +[Active/Active](/terraform/enterprise/deploy/replicated/install/automated/active-active) +architecture. + +You are responsible for providing and maintaining the external PostgreSQL +server, S3-compatible object storage, and Redis instance. + +Active/Active stores configuration data on a Docker volume on the instance. Use +`replicatedctl app-config export` to retrieve the configuration data. + +### When to Use Active/Active + +We recommend Active/Active for the following use cases: + +- Your environment has an external PostgreSQL server, S3-compatible object storage, and Redis instance. +- You have experience managing a PostgreSQL server such as Amazon RDS for PostgreSQL, Google Cloud SQL for PostgreSQL, Azure Database for PostgreSQL, etc. +- You have experience managing an S3-compatible object storage location such as AWS S3, Azure Blob Storage, Google Cloud Storage, MinIO, etc. +- You have experience managing a Redis instance such as AWS ElastiCache for Redis, Azure Cache for Redis, Google Cloud Memorystore for Redis, etc. +- You want to use native backup and restore features provided by the external PostgreSQL server and S3-compatible object storage. +- You want to scale beyond a single instance of Terraform Enterprise to increase reliability and performance. + +## Mounted Disk + +The Mounted Disk operational mode stores the PostgreSQL Database and Object +Storage data in a directory on the instance. It is expected that this directory +is backed by persistent storage that you can mount to the instance. This allows +you to backup and restore the PostgreSQL Database or Object Storage data +independently of the Terraform Enterprise instance. + +You are responsible for providing and maintaining the persistent storage. + +Mounted Disk stores configuration data on a Docker volume on the instance. Use +`replicatedctl app-config export` to retrieve the configuration data. + +### When to Use Mounted Disk + +We recommend Mounted Disk for the following use cases: + +- Your environment does not have an external PostgreSQL server or S3-compatible object storage. +- You have experience managing persistent storage such as an AWS EBS volume, an Azure Managed Disk, a Google Cloud Persistent Disk, an iSCSI location, etc. +- You are familiar with using tools like `cp`, `scp`, and `rsync` to backup and restore data. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/pre-install-checklist.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/pre-install-checklist.mdx new file mode 100644 index 0000000000..b936c16cff --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/pre-install-checklist.mdx @@ -0,0 +1,43 @@ +--- +page_title: Pre-Install Checklist - Before Installing - Terraform Enterprise +description: >- + Make key architecture decisions and prepare infrastructure and data files for + Terraform Enterprise. +--- + +# Terraform Enterprise Pre-Install Checklist + +Complete all of the following tasks before installing Terraform Enterprise. + +## Choose an Operational Mode + +Choose an [operational mode](/terraform/enterprise/deploy/replicated/install/operation-modes) for Terraform +Enterprise. Each operational mode has a different approach to data +[reliability and availability](/terraform/enterprise/deploy/replicated/architecture/system-overview/reliability-availability). +You must make this decision before you begin installation because some modes +have additional requirements. You cannot change the operational mode once +Terraform Enterprise is running. + +## Obtain Credentials + +You must obtain an Enterprise license and a TLS certificate for Terraform Enterprise to use. If you choose the external services operational mode, Terraform Enterprise requires access to an S3-compliant endpoint for object storage. Refer to [Credentials](/terraform/enterprise/deploy/replicated/requirements/credentials) for details. + +## Prepare Data Storage + +Make sure your data storage services or device meet Terraform Enterprise's requirements. These differ depending on the operational mode you choose for your instance. Refer to the following for your use case: + +- [Operational Mode Data Storage Requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements) +- [PostgreSQL Requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements) +- [Minio Setup Guide](/terraform/enterprise/deploy/replicated/requirements/data-storage/minio-setup-guide) +- [Externally Managed Vault](/terraform/enterprise/deploy/replicated/install/vault) + +## Configure Linux Instance + +You must prepare a running Linux instance for Terraform Enterprise before running the installer. This might require additional configuration or software installation, depending on the operating system (OS) and your operational requirements. You will start and manage this instance like any other server. + +Configure the following for the Linux Instance: + +- **Operating System:** Refer to [Supported OS](/terraform/enterprise/deploy/replicated/requirements/os-specific/supported-os) for details. +- **Hardware:** Incorrect amounts of disk space or memory can cause significant performance issues. Refer to [Hardware Requirements](/terraform/enterprise/deploy/replicated/requirements/hardware) for details. +- **Network:** Terraform Enterprise is a networked application. Its Linux instance(s) must allow several kinds of incoming and outgoing network traffic. Refer to [Network Requirements](/terraform/enterprise/deploy/replicated/requirements/network) for details. +- **Docker Engine:** Terraform Enterprise requires a Docker engine. Refer to [Docker Requirements](/terraform/enterprise/deploy/replicated/requirements/docker_engine) for configuration details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/uninstall.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/uninstall.mdx new file mode 100644 index 0000000000..8df99b5492 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/uninstall.mdx @@ -0,0 +1,248 @@ +--- +page_title: Uninstall - Terraform Enterprise +description: >- + Learn to run a script that removes Terraform Enterprise and all of its + services (excluding Docker) from a system. +--- + +# Uninstall Terraform Enterprise + +If you installed Terraform Enterprise on VMware instances, you may not be able to easily request new virtual machines for a broken or corrupted installation. Instead, you can use the `uninstall` script to remove Terraform Enterprise and all of its services (excluding Docker) from a system. This includes the default Replicated snapshot directory - `/var/lib/replicated/snapshots`. If you have Replicated snapshots you wish to keep, please back up this directory before running the uninstall script. + +~> **Important**: This script does not touch the mounted disk path, so you will need to manually clean that up if necessary. + +Please contact [support][support] with questions or issues. + +## While the Script Runs + +After you initiate `uninstall`: + +1. Enter `yes` when asked if you want to continue with the installation. + + ``` + $ sudo ./uninstall.sh + This script will completely uninstall Terraform Enterprise and Replicated on this system, as well as remove associated files. + Do you wish to continue? (y/n)yes + Proceeding with uninstall... + ``` + + If there are snapshots present on the system, choose whether to move them to another directory, delete them, or cancel the uninstall. Here is an example of moving snapshots to another directory: + + ``` + There appear to be Replicated snapshots stored in /var/lib/replicated/snapshots. + 1) Move the snapshots to another directory + 2) Continue uninstall and delete the snapshots + 3) Cancel the uninstall + Select an option: 1 + Enter the directory to move the snapshots to: /tmp + The snapshots will be moved to /tmp. + Press Y to continue or N to cancel. y + Moving snapshots... + Files moved. + ``` + + The script continues and stops the Replicated services, removes the Docker containers, and removes Replicated executables and configuration files from the system. + + ``` + Stopping and disabling the replicated services... + Removed /etc/systemd/system/docker.service.wants/replicated-operator.service. + Removed /etc/systemd/system/docker.service.wants/replicated.service. + Removed /etc/systemd/system/docker.service.wants/replicated-ui.service. + Replicated services stopped and disabled. + Stopping any running application containers + a8dd38ebcc67 + 11a3c7d476a3 + 45f786c7c632 + 31664ff29012 + c0122c1dce13 + 8c6b98b6d498 + d3856e83038d + b5e160999e2b + a7f69f5507de + 45a07127fa15 + 7a364889673d + d5f6218e1d3c + 3f10e192a503 + 818bb2464291 + 1bd96c43b48d + 8388555131dd + 0a0cb265a2bf + rabbitmq + telegraf + influxdb + anchor_isolation_network + Removing Replicated Docker containers... + replicated + replicated-ui + replicated-operator + replicated-premkit + replicated-statsd + retraced-api + retraced-processor + retraced-cron + retraced-nsqd + retraced-postgres + Removing Replicated files and executables... + Run systemctl daemon-reload... + Terraform Enterprise and Replicated should now be uninstalled. + ``` + +1. Choose an option to prune Docker volumes: + +- Select `Prune all Docker volumes` if you only use this system for Terraform Enterprise. +- Select `Prune only application Docker volumes` to prune only Replicated and Hashicorp Docker volumes and leave the rest intact. +- Select `Skip this step` to leave all Docker volumes intact. + + ``` + I can now clean up the Docker images for you. + 1) Prune all Docker volumes + 2) Prune only application Docker volumes + 3) Skip this step + Select an option: 1 + Prunning all Docker volumes... + WARNING! This will remove: + - all stopped containers + - all networks not used by at least one container + - all volumes not used by at least one container + - all images without at least one container associated to them + - all build cache + + Are you sure you want to continue? [y/N] y + Deleted Containers: + a8dd38ebcc67ab878ba60fa740df494ff91922aba04f205d675b6a7e4c6d451e + 11a3c7d476a3e1515c97d882c4cc7db8df64b9b7b491575197e57decb45b525c + 45f786c7c632aac83e4ebf5e939a20651fb8026e1123977eee8a842f1bbcbed1 + 31664ff29012ee7192abb82e8dcbce4ee564e92a24e6de8a03e948a5ca2eb8c5 + 848813ade8b911d356945e309194deed2ba73f165b36ed252a01b2206366ef1c + 1e040b17eb8aca1275dff36dc7175edcb32ab684a697380e9862c436fae8d9f1 + c0122c1dce13b85177987c53c41cbbaf9cf39442601a5360a066e527c022275a + 8c6b98b6d498114a2e71e979dd3c6ef01006b4b80d94a5f39a1b850c6aaae8f0 + 5f2760b94e171fd86c643096f0df6603477899abf4fdde690e40dc35d1bdfd8b + d3856e83038dad46cfbdfe8e39ad57a5896d29b2feab6d4ac1089b18e51e2c9c + 83e2a6ffe045b97cdcec150f3e283e53b19bd90380359fa3db85ba6706a3ca46 + b5e160999e2b7c9d82cbb1217463a844c0a9c54af6c0f4129640e780d712bee8 + c638514eecccff260aabd7d634fd49c34d3938d679d485beb463eb0c58821ca8 + a7f69f5507de8e1501ee9324fc2a82f4e12d2784143ced4500d4036f8f807317 + 45a07127fa15d75161b1764dba060bae6b1115fd567cf9966a59c200d912ad23 + 7a364889673df8a645776b36d538c1429559673d3cc808e68f408939faa6cb35 + 01b60968a765c70c9a72b901ac8e6389805e65c6e158eee9ac588f347b6aaa33 + d5f6218e1d3c016a95740affdd591c64d34dfb8bb2717c18ce4b667fafc272ff + 3f10e192a5038fabc94fda54cad3877ff88865d34f460fe0d02500eca965ea9a + 818bb2464291c5e0b7c6d65c0d10790a57ad95e040d770b1a5df2e7efe093242 + a3ddfd00b603a5dd71f382f9312965de222544fc5938b3f968df36b4c7cab8e3 + 715e6c1fe62eada1da160d0011bc2c26e336a233be5543dabad2dd67cd99994c + d851bcb83703d95553b1a276532861d7e6b790166609102b5134b6befdb9c905 + 16da96c20b2f43d849703524effddf6100a54a6aed3bee9878ca4e3b2b47f742 + c10e0d567406699e3c3bb97225f4ebe94541e8a4a1edf77592b68e06ee778a4b + 1bd96c43b48d2634b251ead68575a7bfba255f52a9909d2f0c00a5f5dd6cd14e + 8388555131dd1ec8f9d9d218295d35ff287f9038430848ee2d721fd92c896b83 + 473ec860bc666b3265e4c50415bca607011f857024b8469f5aeffe0a251935e8 + 0a0cb265a2bfa773086d2a98a3a6412c1d54eaacad6706f319315485c9825996 + dbf1b59e8b8451c0ece04fb57fc42aef4b6accb53fbcbe5850ed873a806f64a9 + 73bccf22ef84311ccf6dc2fa608191c8321fd77b4444c0406933c0eca7886bc9 + ``` + +The script removes dangling Docker volumes and the Docker networks that were created for the application. You may see errors such as the ones below, these are normal and just mean the script is attempting to clean up something that's already been removed. + +```` +``` +Deleted Networks: +tfe_terraform_isolation +replicated_retraced +tfe_services + +Deleted Volumes: +rabbitmq +d8e5aa7b8454be6b2a1e3e230170eccd6b4e46e1a79af86bb2bcbfbc09665a04 +17e584502a4b54a28ef5a54bdf884f0e8f4912071e52db2786379197f12d2c45 +cf8a92056862b7e6322658c900162d5fdf6d4528b4a247139a7dcf33b7d689aa +70ff9f127bfab073cf6d855bde073f2f97d715ab5af6fa28908d54ba31204608 +88189c95b0bdc5dc97e027dafd9ac077838d6ddbf295273c1c44c44478f1c815 +influxdb +config +66e70bcfc0cf10f28c2d4e0dbe445d37d7953b4a20e010f3b23790901f49f95a +a063cc63466436ef9992c03936c0c26d0cfa150d3f3ffaa7156cec62b788903c +10f6c1f088586fbb903cb5f368fd3f14eed47803d91df9c75d1d976f00b17af9 +471f949aff03bd40f9bcf61d4da0e0fd1c2aab7f49e0673fa2a469442eb3c78c +6b973f2ec922cfe902a0fb8d2fc6dead476c0f55f1ab9b73833665a2330ad947 +a5abdb8ab07d354cd1cc2a0368681718da632527e0efd79593e3805ac517261c +f3777b2b116e9734fa8e10514caeb1f51f4a1770896094fbb74904346fa5f18b +redis +e9c8c5566302e65db0d39c1c7c8ca5d886599f535eec5c655b9e99eac73042e8 +5a41d77a1085b1fccd450804484f989e9bc5c21351666e7dcfe4d20a56c4fd4b +090ed8544eb926967c55d5343bc291d14a95534fb6ed3d7c2cd510af83c11786 +79e2e42e6a316129c0c9ff0314c774652b1c8d70029385ec55583cd6efbae8a8 +nomad-workers +b0c7e5919e3185bf09a15fd8e466db614a82aaf6987f38ac656a396561499f30 +cc70bd77c11fedf6d0b656eb474e83893fd9a0d0db6e421686adf2defb4eade1 +aux +c749451acfc48aa4b355248d90aaf667c7ab2bc1818fadfbd9fd91b7c9710b34 +09a6d3e6ac704ac1e151ae925f0bb25ce24f5a330b9d2ffd69f2a9fa0db1abc9 + +Deleted Images: +untagged: hashicorp/build-worker:now +deleted: sha256:378b3ecd0a947d834964ab4f690189923c884417d6c9a6fa58989b99330c570f +deleted: sha256:c7155461ae7897540d42450b157c5584a3ca53a92c0fca151c1b163fd6458176 +deleted: sha256:82c7cbdecbe94986e0a3880702679a42badfc925eb81a5f0e1d23be4a1c4375d +untagged: 10.1.0.20:9874/hashicorp-ptfe-rabbitmq:9e22de8 +untagged: registry.replicated.com/terraformenterprise/uagwz2oacr7rk.hashicorp-ptfe-rabbitmq:9e22de8 +untagged: registry.replicated.com/terraformenterprise/uagwz2oacr7rk.hashicorp-ptfe-rabbitmq@sha256:b70a3d010ff77616b1036d96942aa016973ef58c60faf3030c94ceb84cd2867b +deleted: sha256:11de65e463132236bd73df48a8ffa490ff2b525a6fadf8f89e876b7a50c59efc +deleted: sha256:e50dc68f15e464a836e20ff11ce3d436c0950ffdf81669987a91b5f67a600222 +deleted: sha256:931118288655ef2e98fa288528cfe5bc325a092d9a729e0ed663ac95cb4c3643 +deleted: sha256:b41fbc32924dfe39aa506aacc31029ac0cae428e0afc48ce710abadf6c3c248b +deleted: sha256:d2fafd954f9d13009ae22483bc6767f8c13621f0a00fe7516f6a53ca02b872e9 +deleted: sha256:11d8011c83b4c445be64bab28e30c8776e69cda90a739663c3f57b55ed83a519 +deleted: sha256:751e8ca997e66f4b7892df7c90f70933380598e9c32394ff787642988272a679 +deleted: sha256:56cedf40e0080b58fe0bda77607e4321b658f6486de25f6750334e60827d239c +deleted: sha256:5987af1ce8b66c0ac9bc8fca0a58b29dcf283e756bafad1b9347a1e6a6f907e3 +deleted: sha256:58f67ec54ffec23435af7a061e142547586ad71d2ca083845bc3b5a024965143 +untagged: 10.1.0.20:9874/hashicorp-tfe-telegraf:1.16.3-alpine +... + +Total reclaimed space: 6.168GB +Done. +Removing the Replicated and TFE Docker networks... +Error: No such network: replicated_retraced +Error: No such network: tfe_services +Error: No such network: tfe_terraform_isolation +Unable to remove all Docker application networks, or none to be removed. +Done. +Removing any dangling Docker volumes... +"docker volume rm" requires at least 1 argument. +See 'docker volume rm --help'. + +Usage: docker volume rm [OPTIONS] VOLUME [VOLUME...] + +Remove one or more volumes +Unable to remove dangling Docker volumes, or none to be removed. + +Uninstall Complete +``` +```` + +## Run the Uninstaller + +### Online + +If the system can reach [install.terraform.io][install], go to a shell on your instance and run one of the following: + +- **Download the uninstaller**: Run `curl https://install.terraform.io/tfe/uninstall > uninstall.sh`. + +- **Make the script executable**: Run `chmod +x uninstall.sh`. + +- **Execute the uninstaller**: Run `sudo bash uninstall.sh` to execute the script. + +### Airgapped + +If the system cannot reach [install.terraform.io][install]: + +1. [Download the uninstall script][uninstall link] from a machine that has access to [install.terraform.io][install], and upload the script to the Terraform Enterprise server. + +1. From a shell on your instance, run `sudo bash uninstall.sh`. + +[install]: https://install.terraform.io/tfe/uninstall + +[uninstall link]: https://install.terraform.io/tfe/uninstall + +[support]: https://support.hashicorp.com diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/vault.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/vault.mdx new file mode 100644 index 0000000000..1f3e804195 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/install/vault.mdx @@ -0,0 +1,30 @@ +--- +page_title: External Vault - Terraform Enterprise +description: >- + Learn about the data storage requirements of using an external Vault server with Terraform Enterprise. +--- + +# External Vault Requirements for Terraform Enterprise + +Terraform Enterprise automatically creates an internally-managed Vault server +that stores its data in the PostgreSQL Database. We strongly recommend that +organizations use this internally-managed Vault server. However, some +organizations have specific requirements around data encryption and auditing. +Those organizations can configure Terraform Enterprise to use an external Vault +server rather than the internally-managed Vault server. + +We only recommend using external Vault when you have experience managing Vault +in production. This approach requires that you assume full responsibility for +the Vault server, including sealing, unsealing, replication, etc. + +!> **Warning:** Do not configure multiple Terraform Enterprise instances to use the same namespace on an external Vault server unless they are part of an [Active/Active](/terraform/enterprise/deploy/replicated/install/automated/active-active) installation. Doing so will result in data loss. + + +### External Vault Configuration + +~> **Important:** You must configure External Vault during initial installation. After installation, you can only change the configuration using the [backup and restore API](/terraform/enterprise/deploy/replicated/administration/infrastructure/backup-restore). + +Run the following commands to configure your external Vault server for use with +Terraform Enterprise. + +@include "replicated-and-fdo/requirements/vault-partial.mdx" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/monitoring/logging.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/monitoring/logging.mdx new file mode 100644 index 0000000000..ff373555c7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/monitoring/logging.mdx @@ -0,0 +1,179 @@ +--- +page_title: Log Forwarding - Infrastructure Administration - Terraform Enterprise +description: >- + Use log forwarding to increase observability, meet retention requirements, and aid troubleshooting. Learn how to configure forwarding, and audit and rotate logs. +--- + +# Terraform Enterprise Log Forwarding + +Terraform Enterprise supports forwarding its logs to one or more external +destinations, a process called log forwarding. Log forwarding provides increased +observability, assistance complying with log retention requirements, and +information during troubleshooting. + +## Requirements + +Log forwarding requires: + +- Terraform Enterprise running on an instance using `systemd-journald`. Execute + `systemctl status systemd-journald` to check if the `systemd-journald` service + is started and enabled. +- A version of Docker that supports the `journald` logging driver. Execute + `docker info --format '{{.Plugins.Log}}'` to check if the `journald` plugin is + listed. +- Network connectivity between Terraform Enterprise and the external + destination(s) where logs should be forwarded. + +## Enable Log Forwarding + +Log forwarding is disabled by default. To enable log forwarding, set the +`log_forwarding_enabled` Terraform Enterprise application setting to the value +`1`. + +```sh +tfe-admin app-config -k log_forwarding_enabled -v 1 +``` + +When log forwarding is enabled, the Terraform Enterprise application settings +show the following for `log_forwarding_enabled`: + +```json + "log_forwarding_enabled": { + "value": "1" + }, +``` + +-> **Note**: [Automated license utilization reporting](/terraform/enterprise/deploy/replicated/administration/license/automated-license-utilization-reporting) (which securely sends HashiCorp the minimum data required to validate license utilization) is on by default. + +## Configure External Destinations + +The `log_forwarding_config` Terraform Enterprise application setting must +contain valid +[Fluent Bit `[OUTPUT]` configuration](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit) +specifying +[supported external destination(s)](#supported-external-destinations) +where Terraform Enterprise should forward logs. The default configuration does +not forward any logs. + +Since the Terraform Enterprise application settings are stored as JSON +strings, we recommend first creating a `fluent-bit.conf` file with the valid +Fluent Bit `[OUTPUT]` configuration and then using that file to configure the +`log_forwarding_config` application setting. This method ensures that the +configuration is stored in the application settings exactly how it appears in +the `fluent-bit.conf` file. + +For a Standalone installation of Terraform Enterprise: + +```sh +replicatedctl app-config set log_forwarding_config --value "$(cat fluent-bit.conf)" +``` + +For an Active/Active installation of Terraform Enterprise: + +```sh +tfe-admin app-config -k log_forwarding_config -v "$(cat fluent-bit.conf)" +``` + +Once configured, the Terraform Enterprise application settings show the +`log_forwarding_config` setting in escaped JSON string format: + +```json + "log_forwarding_config": { + "value": "# Match all logs and do not forward them anywhere.\n[OUTPUT]\n Name null\n Match *\n" + }, +``` + +That escaped JSON string renders to the following: + +```ini +# Match all logs and do not forward them anywhere. +[OUTPUT] + Name null + Match * +``` + +To forward logs to multiple external destinations, use multiple `[OUTPUT]` +directives. + +```ini +# Forward all logs to Datadog. +[OUTPUT] + Name datadog + Match * + ... + +# Forward all logs to Fluent Bit or Fluentd. +[OUTPUT] + Name forward + Match * + ... +``` + +-> **Note:** Do not use an `[OUTPUT]` directive with the +[`stdout` Fluent Bit output plugin](https://docs.fluentbit.io/manual/pipeline/outputs/standard-output). +Doing this creates a loop that continuously emits logs! + +### Restart Terraform Enterprise + +Once log forwarding is enabled and configured, you need to restart Terraform +Enterprise for the changes to take effect. [Learn how to restart Terraform Enterprise](/terraform/enterprise/deploy/replicated/administration/infrastructure/mounted-to-external-migration#restart-terraform-enterprise). + +## Supported External Destinations + +You can only forward logs to one of the supported external destinations below. +Each supported external destination contains example configuration for convenience. + +@include "replicated-and-fdo/monitoring/logging/supported-destinations-partial.mdx" + +## Audit Logs + +Terraform Enterprise emits its audit logs along with its application logs. +Currently, log forwarding can forward either all Terraform Enterprise logs or no +logs at all. To distinguish audit logs from application logs, audit log entries +contain the string `[Audit Log]`. + +Here's an example audit log entry formatted for readability: + +```json +2021-08-31 04:58:30 [INFO] [7a233ad1-c50c-4737-a925-3be901e55fcb] [Audit Log] +{ + "resource":"run", + "action":"create", + "resource_id":"run-nL77p69bsesoF3RK", + "organization":"example-org", + "organization_id":"org-pveSPvxocni226Fn", + "actor":"example-user", + "timestamp":"2021-08-31T04:58:30Z", + "actor_ip":"19.115.231.192" +} +``` + +If you have a requirement to split audit logs from application logs, we +recommend forwarding all Terraform Enterprise logs to a log aggregation system, +filtering the audit logs based on the `[Audit Log]` string, and forwarding just +the audit logs to the desired destination. + +## Log Rotation + +Log forwarding uses the `journald` Docker logging driver to send Terraform +Enterprise logs to `systemd-journald`. This can cause increased disk utilization +for the `/var/log/journal` path. + +To limit disk utilization, configure the `SystemMaxFileSize` and +`SystemMaxFiles` settings within `/etc/systemd/journald.conf`. + +The following configuration tells `systemd-journald` to use up to 7GB of disk +space by limiting the size a log file to 1024MB and keeping up to 7 files at any +given time: + +```ini +[Journal] +SystemMaxFileSize=1024M +SystemMaxFiles=7 +``` + +To apply these changes, restart `systemd-journald`: + +```sh +sudo systemctl restart systemd-journald +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/monitoring/monitoring.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/monitoring/monitoring.mdx new file mode 100644 index 0000000000..6d90a63c5a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/monitoring/monitoring.mdx @@ -0,0 +1,94 @@ +--- +page_title: Monitoring - Infrastructure Administration - Terraform Enterprise +description: >- + Learn how to use health checks, metrics, and telemetry to monitor the health of your Terraform Enterprise instance. +--- + +# Monitoring a Terraform Enterprise Instance + +This document outlines best practices for monitoring a Terraform Enterprise instance. + +## Health Check + +Terraform Enterprise provides a `/_health_check` endpoint on the instance. If Terraform Enterprise is up, the health check will return a `200 OK`. + +The `/_health_check` endpoint operates in 2 modes: + +- Full check +- Minimal check + +With a full check, the service will attempt to verify the status of internal components and PostgreSQL, in contrast to a minimal check which returns `200 OK` automatically after a successful full check. + +The endpoint's default behavior is to perform a full check during startup of the instance, and minimal checks after Terraform Enterprise is active and running. + +-> **Note:** If you wish to force a full check, an additional query parameter is required: `/_health_check?full=1`. Take extra caution as every call will make requests to internal components and PostgreSQL, increasing system load and latency. + +## Metrics & Telemetry + +In addition to health-check monitoring, we recommend monitoring standard server metrics on the Terraform Enterprise instance: + +- I/O +- RAM +- CPU +- Disk + +As of the `v202201-1` release, Terraform Enterprise supports exporting container-level resource utilization metrics. + +### Terraform Enterprise Metrics + +The Terraform Enterprise Metrics service collects a number of runtime metrics. Operators can use this data to gain real-time visibility into their installation. Additionally, these metrics can be used to set up monitoring and alerting to detect anomalous incidents, performance degradation, and utilization trends. Metrics are aggregated on a five second interval and are retained in memory for fifteen seconds. In order to leverage Terraform Enterprise metrics in monitoring, data must be stored in metric aggregation software. Terraform Enterprise currently supports exposing metrics data in Prometheus format, as well as a JSON representation. + +#### Enable Metrics Collection + +Metrics collection can be configured with the `metrics_endpoint_enabled` config flag in the [application config file](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#application-settings). By default, `metrics_endpoint_enabled` is set to `"0"` (disabled). To enable metrics collection, set this value to `"1"`. + +#### Access Metrics + +When enabled, Terraform Enterprise will expose metrics on a port separate from the application. This allows operators to use network access controls to restrict access to metrics data to authorized consumers, i.e., a Prometheus server. By default, port 9090 is used for plaintext HTTP requests, and port 9091 for HTTPS traffic. Both of these values are configurable via the `metrics_endpoint_port_http` and `metrics_endpoint_port_https` configuration values, respectively. + +Both the HTTP and HTTPS ports will respond to HTTP requests with the path `/metrics`. By default, requests to the `/metrics` endpoint will generate a response in JSON format; adding the query string `?format=prometheus` will generate a response in Prometheus format. + +When using Prometheus, it is recommended to use a scrape interval shorter than the expiration time of 15 seconds, to ensure that data points from short-lived processes are not missed. + +#### Container Metrics + +These metrics report runtime information about Terraform Enterprise containers. + +| Exposed Metric | Metrics Type | Description | +| :---------------------------------------- | :----------: | :--------------------------------------------------------------------------------------------------------------- | +| `tfe.container.cpu.usage.user` | `counter` | Running count, in nanoseconds, of the total amount of time processes in the container have spent in userspace | +| `tfe.container.cpu.usage.kernel` | `counter` | Running count, in nanoseconds, of the total amount of time processes in the container have spent in kernel space | +| `tfe.container.memory.used_bytes` | `gauge` | The amount of memory allocated to the container in bytes, minus memory that is used for page cache | +| `tfe.container.memory.limit` | `gauge` | The maximum amount of memory in bytes that can be allocated by the container | +| `tfe.container.network.rx_bytes_total` | `counter` | Running count of the number of network bytes received by the container | +| `tfe.container.network.rx_packets_total` | `counter` | Running count of the number of network packets received by the container | +| `tfe.container.network.tx_bytes_total` | `counter` | Running count of the number of network bytes transmitted by the container | +| `tfe.container.network.tx_packets_total` | `counter` | Running count of the number of network packets transmitted by the container | +| `tfe.container.disk.io_op_read_total` | `counter` | Running count of the number of read disk operations executed by the container | +| `tfe.container.disk.io_op_write_total` | `counter` | Running count of the number of write disk operations executed by the container | +| `tfe.container.disk.io_bytes_read_total` | `counter` | Running count of the number of disk bytes read by the container | +| `tfe.container.disk.io_bytes_write_total` | `counter` | Running count of the number of disk bytes written by the container | +| `tfe.container.process_count` | `gauge` | The number of processes active within the container | +| `tfe.container.process_limit` | `gauge` | The maximum number of processes that can be executed inside the container | + +The following metadata labels will be added to each container metric emitted: + +- `id`: The container ID +- `name`: The container name +- `image`: The container image + +Build worker container metrics include four additional labels: `run_type`, `run_id`, `workspace_name`, and `organization_name`. You can use these labels to associate a build worker container with its type, run, workspace, and organization, respectively. Metrics for long-running service containers will not include these labels. + +In addition to the per-container metrics, the following global metrics are exposed: + +| Exposed Metric | Metrics Type | Description | +| :---------------------- | :----------: | :-------------------------------------------------------------------------------- | +| `tfe.run.count` | `gauge ` | Number of running containers being used for Terraform operators (runs and plans) | +| `tfe.run.limit` | `gauge` | Maximum number of jobs as defined by the `capacity_concurrency` Replicated config | +| `tfe.run.current.count` | `gauge` | Number of active Terraform runs labeled by organization, workspace, and status | + +The name and ID for build worker containers are unique for each build, and build container names take the form of a UUID. Be aware of this when planning for Prometheus storage capacity requirements that relate to metric cardinality. Environments that do not need to track resource consumption of individual build containers or runs can use [Prometheus metric relabelling](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs) to remove the unique ID, name, and run type labels from container metrics. This reduces cardinality within the dataset while still retaining the ability to associate resource usage with a given workspace and organization. + +#### Grafana Dashboard + +This [template Grafana dashboard](https://grafana.com/grafana/dashboards/15630) demonstrates how you can use Grafana and Prometheus to visualize exported Terraform Enterprise metrics. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/credentials.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/credentials.mdx new file mode 100644 index 0000000000..dcc74fbebd --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/credentials.mdx @@ -0,0 +1,87 @@ +--- +page_title: Credentials - Requirements - Terraform Enterprise +description: >- + You must obtain a license file from HashiCorp, a TLS certificate, and a + private key. +--- + +# Credentials + +Terraform Enterprise requires the following credentials and permissions. + +## License File + +To deploy Terraform Enterprise, you must obtain a license file from HashiCorp. + +## TLS Certificate and Private Key + +Terraform Enterprise requires a TLS certificate and private key in order to operate. This certificate must match Terraform Enterprise's hostname, either by being issued for the FQDN or being a wildcard certificate. + +The certificate can be signed by a public or private CA, but it _must_ be trusted by all of the services that Terraform Enterprise is expected to interface with; this includes your VCS provider, any CI systems or other tools that call Terraform Enterprise's API, and any services that Terraform Enterprise workspaces might send notifications to (for example: Slack). Due to these wide-ranging interactions, we recommend using a certificate signed by a public CA. + +The key and X.509 certificate must be PEM (base64) encoded, and should be provided to the installer as text. + +~> **Important:** If you use a certificate issued by a private Certificate +Authority, you must provide the certificate for that CA in the +`Certificate Authority (CA) Bundle` section of the installation. This allows services +running within Terraform Enterprise to access each other properly. +See [Installation: Certificate Authority (CA) Bundle](/terraform/enterprise/deploy/replicated/install/interactive/installer#certificate-authority-ca-bundle) +for more on this. + +Terraform Enterprise validates the certificate to ensure it uses a Subject Alternative Name (SAN) for Domain Names (DN) entries and not just a Common Name (CN) entry. + +## IAM Policies - External Services Mode + +If you choose the [external services operational mode](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#choose-an-operational-mode), Terraform Enterprise requires access to an S3-compliant endpoint for object storage. You can grant access to the object storage endpoint by either assigning an AWS instance profile or an equivalent IAM system in non-AWS environments. + +### S3 Policy + +At a minimum, Terraform Enterprise requires the following S3 permissions: + +``` +{ + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:ListBucket", + "s3:GetObject", + "s3:DeleteObject", + "s3:GetBucketLocation" + ], + "Resource": [ + "", + "/*" + ] +} +``` + +-> **Note:** The `s3:ListAllMyBuckets` permission is necessary when testing authentication via the Replicated web console. However, the permission is not required for Terraform Enterprise to function and can be removed once the authentication is successfully tested. + +### KMS Policy + +At a minimum, Terraform Enterprise will require the following permissions if the objects in the bucket are to be encrypted via resources in AWS's KMS: + +``` +{ + "Effect": "Allow", + "Action": [ + "kms:Decrypt", + "kms:Encrypt", + "kms:DescribeKey", + "kms:ReEncrypt*", + "kms:GenerateDataKey*" + ], + "Resource": [ + "" + ] +} +``` + +### Instance Profile as Default Credentials + +You can use Terraform Enterprise's instance profile to provide default credentials to workspaces. When using IMDSv2, configure the PUT response hop limit with a value of 2 within the [instance metadata options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html). Terraform will attempt to use the instance profile to provision resources when you do not set credentials as environment variables. However, this approach presents a few security risks: + +1. All workspaces will have the same permissions because they have access to the same instance profile. You cannot selectively allow or deny access to the instance profile for each workspace. +1. Workspaces will share the instance profile with the Terraform Enterprise application. All workspaces within the application will have access to any resources that Terraform Enterprise depends on, such as its S3 bucket, KMS keys, etc. + +~> **Important:** If you choose not to use the instance profile for default credentials, we highly recommend that you [restrict build worker metadata access](/terraform/enterprise/deploy/replicated/architecture/system-overview/security-model#restrict-terraform-build-worker-metadata-access) to prevent workspaces from accessing the instance profile. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/minio-setup-guide.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/minio-setup-guide.mdx new file mode 100644 index 0000000000..9109e6afc3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/minio-setup-guide.mdx @@ -0,0 +1,7 @@ +--- +page_title: Minio Setup Guide - Installation - Terraform Enterprise +description: >- + Learn how to set up Minio for external object storage for HashiCorp Terraform Enterprise. +--- + +@include "replicated-and-fdo/requirements/minio-partial.mdx" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements.mdx new file mode 100644 index 0000000000..806e5e1cb1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/operational-mode-requirements.mdx @@ -0,0 +1,32 @@ +--- +page_title: Operational Mode Requirements - Requirements - Terraform Enterprise +description: >- + Learn about the data storage requirements for each Terraform Enterprise operational mode. +--- + +# Operation Mode Data Storage Requirements + +Terraform Enterprise data storage requirements differ based on the +[operational mode](/terraform/enterprise/deploy/replicated/install/operation-modes) +you choose for your instance. If you are following one of the +[reference architectures](/terraform/enterprise/deploy/replicated/architecture/reference-architecture), we recommend referring to it while preparing your data storage services. + +## External Services Mode + +External Services mode has the following requirements: + +- [PostgreSQL Requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements) +- Any S3-compatible object storage service, GCP Cloud Storage or Azure blob storage meets Terraform Enterprise's object storage requirements. You must create a bucket for Terraform Enterprise to use, and specify that bucket during installation. Depending on your infrastructure provider, you might need to ensure the bucket is in the same region as the Terraform Enterprise instance. + - Disable any lifecycle rules that would delete, archive, or transition objects in this container. Terraform Enterprise expects to manage all data the object storage service, so any lifecycle moves may result in unexpected data inconsistencies. + +@include "replicated-and-fdo/requirements/operation-modes-partial.mdx" + +### Database Maintenance + +There are three CLI commands available as of v202005-2 to facilitate management of the PostgreSQL database that runs on the host as part of the Mounted Disk operational mode: + +- `replicated admin db-backup`: This will run a `pg_dump` and store the backup in `/backup/ptfe.db` on the host. +- `replicated admin db-restore`: This will run a `pg_restore` using `/backup/ptfe.db` as it's data source. +- `replicated admin db-reindex`: This will run a `REINDEX` against the application database. Note: A reindex can take anywhere from minutes to hours to complete, depending on the size of your database. Running this command locks the database and prevents any other action against it. + +These commands will only display output if there is an error. Please contact [support](https://support.hashicorp.com) if you have any questions or issues with these commands. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements.mdx new file mode 100644 index 0000000000..62584ecd76 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements.mdx @@ -0,0 +1,16 @@ +--- +page_title: PostgreSQL Requirements - Before Installing - Terraform Enterprise +description: >- + Learn about the data storage requirements for PostgreSQL when using the external services operational mode of Terraform Enterprise. +--- + +# PostgreSQL Requirements for Terraform Enterprise + +-> **Note:** These requirements apply to the External Services operational mode, not the Mounted Disk operational mode. Refer to the [Pre-Install Checklist](/terraform/enterprise/deploy/replicated/install/pre-install-checklist) for more information. + + + PostgreSQL v12 will reach end of life on November 12, 2024, and as a result will no + longer be supported in Terraform Enterprise after that date. + + +@include "replicated-and-fdo/requirements/postgres-partial.mdx" diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/docker_engine.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/docker_engine.mdx new file mode 100644 index 0000000000..260d830a55 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/docker_engine.mdx @@ -0,0 +1,119 @@ +--- +page_title: Docker Engine - Legacy Deployment - Requirements - Terraform Enterprise +description: >- + Configure and verify a Docker engine for your Terraform Enterprise + installation. +--- + +# Docker Engine Requirements + +This topic describes the Docker engine requirements for deploy Terraform Enterprise to Replicated. For information about deploying Terraform Enterprise natively to Docker using Docker Compose, refer to [Terraform Enterprise deployment overview](/terraform/enterprise/deploy). Deploying to Docker natively is faster than Replicated deployments and results in faster startups, reduced resource requirements, and improved security. + + +Terraform Enterprise requires **at least one** of the following Docker Engine configurations, in order of preference: + + 1. Docker Engine 23.x - 25.x + +!> **Compatibility warning**: Terraform Enterprise does not yet support the pre-installed Docker version that comes with Amazon Linux 2023. You must uninstall your Docker version and manually install Docker Engine 24.x to ensure compatibility with Terraform Enterprise. + +Docker v20.10 is *only* supported on Amazon Linux 2. Docker v20.10 is no longer receiving updates from Docker, including security updates. Customers using Amazon Linux 2 are encouraged to move to an operating system that supports Docker 23 or 24. In order run Docker v20.10, you will need *one* of the following: + + 1. [`runc` v1.0.0-rc93 or greater](#docker-engine-with-a-compatible-runc-version) + 1. [`libseccomp` 2.4.4 or greater](#docker-engine-with-a-compatible-libseccomp-version) + 1. A [modified `libseccomp` profile](#docker-engine-using-a-modified-libseccomp-profile) + +New online installations of Terraform Enterprise install a supported version of Docker Engine by default. Alternatively, you can install Docker Engine manually as long as you adhere to the above requirements. + +Upgrades to Terraform Enterprise do not upgrade Docker Engine. It is your responsibility to keep Docker Engine up to date within these requirements to ensure stability and security. + +## Docker Compose Compatibility + + Docker Engine comes prepackaged with Docker Compose and compatibility is assessed by meeting the Docker Engine requirements. + + ```sh + # Docker Engine 24.0 + docker compose version + ``` + + +## Docker Engine With a Compatible `runc` Version + + 1. [Install](https://docs.docker.com/engine/install/) a supported Docker Engine version. + + 1. Install the latest version of `containerd` for your operating system. + + On Debian/Ubuntu: + + ```sh + sudo apt install containerd + ``` + + On RHEL/CentOS: + + ```sh + sudo yum install containerd.io + ``` + + 1. Confirm that the installed `containerd` version is 1.4.9, 1.5.5, or greater. + + ```sh + containerd --version + ``` + + 1. Confirm that the installed `runc` version is v1.0.0-rc93 or greater: + + ```sh + runc --version + ``` + + 1. If your Docker Engine and `runc` versions meet the requirements from previous steps, your system is properly configured. Otherwise, proceed to [ option 2](#option-2-docker-engine-with-a-compatible-libseccomp-version). + +## Docker Engine With a Compatible `libseccomp` Version + + -> **Note:** These instructions should only be used if your operating system does not meet the requirements detailed in [Docker Engine With a Compatible `runc` Version](#docker-engine-with-a-compatible-runc-version). + + 1. [Install](https://docs.docker.com/engine/install/) a supported Docker Engine version. + + 1. Install the latest version of `libseccomp` for your operating system. + + On Debian/Ubuntu: + + ```sh + sudo apt install libseccomp2 + ``` + + On RHEL/CentOS: + + ```sh + sudo yum install libseccomp + ``` + + 1. Confirm that the installed `libseccomp` version is 2.4.4 or greater. + + ```sh + runc --version + ``` + + 1. If your Docker Engine and `libseccomp` versions meet the requirements from previous steps, your system is properly configured. Otherwise, proceed to [option 3](#option-3-docker-engine-using-a-modified-libseccomp-profile). + +## Docker Engine Using a Modified `libseccomp` Profile + + -> **Note:** These instructions should only be used if your operating system does not meet the requirements detailed in either [Docker Engine With a Compatible `runc` Version](#docker-engine-with-a-compatible-runc-version) or [Docker Engine With a Compatible `libseccomp` Version](https://terraform.io/docker-engine-with-a-compatible-libseccomp-version). + + 1. [Install](https://docs.docker.com/engine/install/) a supported Docker Engine version. + + 1. Check if the file `/etc/docker/seccomp.json` exists. If it does, proceed to step 4. + + 1. Download the [default moby `libseccomp` profile](https://raw.githubusercontent.com/moby/moby/master/profiles/seccomp/default.json) and save it to the file `/etc/docker/seccomp.json`. + + ```sh + sudo curl -L -o /etc/docker/seccomp.json \ + https://raw.githubusercontent.com/moby/moby/master/profiles/seccomp/default.json + ``` + + 1. In the `/etc/docker/seccomp.json` file, change `"defaultAction": "SCMP_ACT_ERRNO",` to `"defaultAction": "SCMP_ACT_TRACE",`. + + ```sh + sudo sed -i 's/"defaultAction":\s*"SCMP_ACT_ERRNO"/"defaultAction": "SCMP_ACT_TRACE"/1' /etc/docker/seccomp.json + ``` + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/hardware.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/hardware.mdx new file mode 100644 index 0000000000..0dd0f7b2f2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/hardware.mdx @@ -0,0 +1,19 @@ +--- +page_title: Hardware and Data Storage - Requirements - Terraform Enterprise +description: Required disk space and memory for your Terraform Enterprise instance. +--- + +# Hardware and Data Storage Requirements + +You must set up the correct hardware before installing and running Terraform Enterprise. Incorrect amounts of disk space or memory can cause significant performance issues. + +## Hardware + +These requirements provide the instance with enough resources to run the +Terraform Enterprise application as well as the Terraform plans and applies. + +- At least 10GB of disk space on the root volume +- At least 40GB of disk space for the Docker data directory (defaults to `/var/lib/docker`) +- At least 8GB of system memory +- At least 4 CPU cores + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/network.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/network.mdx new file mode 100644 index 0000000000..c9b32ddc30 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/network.mdx @@ -0,0 +1,142 @@ +--- +page_title: Network Requirements - Before Installing - Terraform Enterprise +description: >- + The Linux instance that runs Terraform Enterprise must allow several kinds of + incoming network access. +--- + +# Network Requirements for Terraform Enterprise + +The Linux instance that runs Terraform Enterprise must allow several kinds of incoming network access. Terraform Enterprise also needs to access several external services to handle updates and resource downloads. + +## Ingress + +### Source — User/Client/VCS + +- **443:** Terraform Enterprise application access (HTTPS) + +~> **Important:** Integration with a SaaS VCS provider (GitHub.com, GitLab.com, Bitbucket Cloud, or Azure DevOps Services) requires ingress from the public internet. This lets the [inbound web hooks](/terraform/enterprise/vcs#webhooks) reach Terraform Enterprise. You should also configure appropriate security controls, such as a Web Application Firewall (WAF). + +### Source — Administrators + +- **22:** SSH access (administration and debugging) +- **8800:** Replicated (TFE setup dashboard, HTTPS) + +### Source - Metrics + +- **9090** TCP port on which Terraform Enterprise handles HTTP metrics requests +- **9091** TCP port on which Terraform Enterprise handles HTTPS metrics requests + +The metrics endpoints are optional. You can enable them in the [application settings](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#available-settings) when you install Terraform Enterprise. + +### Source — TFE Server(s) + +- **8201:** Vault HA request forwarding (only necessary when operating in Active/Active mode) + +Additionally, the following ports are used by various application components internally. +This list serves as a point of reference; it is not necessary to expose these ports +for accessibility in a firewall: + +- **2003:** Graphite (Carbon) feeding port (monitoring, metrics) +- **2004:** Graphite (Carbon) feeding port (monitoring, metrics) +- **3121:** Terraform Enterprise private registry +- **4150-4151, 4160-4161, 4170-4171:** Replicated NSQD (messaging platform daemon for internal communication) +- **5432:** PostgreSQL +- **6379:** Redis (application-level caching and coordination) +- **7586:** Terraform Enterprise ingress (pulls in version control system data for application, stores it via Archivist) +- **7588:** Terraform Enterprise state parser +- **7675:** Terraform Enterprise Archivist (stores data in object storage, encrypts it via Vault) +- **8086:** InfluxDB default UDP Service (monitoring, metrics) +- **8125:** StatsD (monitoring, metrics) +- **8200:** Vault (encryption service) +- **9292:** Atlas engine (old name of Terraform Enterprise engine) +- **9870-9880 (inclusive):** host and subnet traffic only; not publicly accessible + - **9873:** Replicated Retraced engine API (Replicated audit subcomponent) + - **9874-9879:** Replicated entry point span +- **23000-23100 (inclusive):** host and subnet traffic only; not publicly accessible + - **23005:** Terraform Enterprise health check point + - **23020:** Nomad (scheduler for Sentinel runs) +- **32774-32776, 49150-49165:** Replicated internal Graphite and StatsD ports (mapped to external ports 2003, 2004, and 8125) + +## Egress + +### Destination - Online Installations + +If Terraform Enterprise is installed in online mode, it accesses the following hostnames to get software updates: + +- `api.replicated.com` +- `get.replicated.com` +- `registry-data.replicated.com` +- `registry.replicated.com` +- `*.quay.io` +- `cdn.quay.io` +- `quay-registry.s3.amazonaws.com` +- `*.cloudfront.net` +- `hub.docker.com` +- `index.docker.io` +- `auth.docker.io` +- `registry-1.docker.io` +- `download.docker.com` +- `production.cloudflare.docker.com` +- `install.terraform.io` + +-> **Note:** We recommend allowing traffic by FQDN and not IP Address or range. IP address allowlists make your service dependent on an external factor, like an external IP address, that you do not control. + +The following hostnames are accessed unless a +[custom Terraform bundle](/terraform/enterprise/run/install-software#custom-and-community-providers) +is supplied: + +- `registry.terraform.io` (when using Terraform 0.12 and later) +- `releases.hashicorp.com` +- `https://yy0ffni7mf-dsn.algolia.net/` - this URL is specific to the Terraform Registry’s [Algolia](https://www.algolia.com/) application. The Terraform Registry uses Algolia to index the current resources in the registry and power HCP Terraform public-facing search for public providers and module curation. +- `github.com` - Public providers and modules are hosted in Github. + +Additionally, unless you have opted out of license entitlement reporting, Terraform Enterprise will need egress access to: + +- `reporting.hashicorp.services` + +~> **Note:** Airgapped installs do not check for updates over the network. + +### Destination - Additional Outbound Network Targets + +Terraform Enterprise also needs egress access to: + +- any VCS servers/services that will be utilized +- login/authentication servers if SAML will be configured (ADFS, Okta, etc) +- the various cloud API endpoints that will be managed with Terraform +- any other third party services that will either be integrated with the Terraform Enterprise server or managed with it. + +### Destination - Cost Estimation APIs + +When [Cost Estimation](/terraform/enterprise/application-administration/integration#cost-estimation-integration) is enabled, it uses the respective cloud provider's APIs to get up-to-date pricing info. + +- `api.pricing.us-east-1.amazonaws.com` +- `cloudbilling.googleapis.com` +- `prices.azure.com` + +~> **Note:** Versions of Terraform Enterprise earlier than v202105-1 used `management.azure.com` and `ratecard.azure-api.net` rather than `prices.azure.com`. + +## Other Configuration + +1. If a firewall is configured on the instance, run one of the following to allow traffic to flow out of the `docker0` interface to the instance's primary address. We recommend doing this before you install Docker. + + - To use UFW, run: `ufw allow in on docker0` + - To use firewalld, run: `firewall-cmd --permanent --zone=trusted --change-interface=docker0` + +1. Get a domain name for the instance. Using an IP address to access the product is not supported as many systems use TLS and need to verify that the certificate is correct, which can only be done with a hostname at present. + +1. **For GCP only:** Configure Docker to use an MTU (maximum transmission unit) of 1460, as required by Google ([GCP Cloud VPN Documentation: MTU Considerations](https://cloud.google.com/network-connectivity/docs/vpn/concepts/mtu-considerations)). + + To configure Docker's MTU, create an `/etc/docker/daemon.json` file with the following content: + + ```json + { + "mtu": 1460 + } + ``` + + ~> **Note:** The above only affects the default network `bridge` aka `docker0`. To apply this to the networks `tfe_services` and `tfe_terraform_isolation`, it is [required](https://support.hashicorp.com/hc/en-us/articles/4405507244691) to delete these two networks and recreate them with the correct MTU for an existing install or to create these two networks prior to installing Terraform Enterprise for a new install. + +1. Ensure the Docker bridge network address is not in use elsewhere on the network. If it is, please refer to the [Docker documentation](https://docs.docker.com/network/bridge/) for information on how to change it. + +~> **Note:** Beginning in version `v202004-1`, non-default Docker networks named `tfe_services` and `tfe_terraform_isolation` were added for the Terraform Enterprise component Docker containers as part of a network segmentation update. Custom configuration [may be required for MTU settings](https://support.hashicorp.com/hc/en-us/articles/4405507244691). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/centos-requirements.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/centos-requirements.mdx new file mode 100644 index 0000000000..d45aa81101 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/centos-requirements.mdx @@ -0,0 +1,33 @@ +--- +page_title: CentOS Linux Requirements - Installation - Terraform Enterprise +description: >- + Learn about the requirements for installing Terraform Enterprise on CentOS Linux. +--- + +# CentOS Requirements for Terraform Enterprise + +When installing Terraform Enterprise on CentOS Linux, ensure you meet the following requirements: + +## Install Requirements + +- A [supported version](/terraform/enterprise/deploy/replicated/requirements/os-specific/supported-os) of CentOS. +- A [supported Docker Engine](/terraform/enterprise/deploy/replicated/requirements/docker_engine) configuration. + +## FAQ + +### Can I use the Docker version in the Extra Packages for Enterprise Linux repository? + +Sure! Just be sure to [modify the default `libeseccomp` +profile](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#option-3-docker-engine-using-a-modified-libseccomp-profile). + +### Which storage driver should I use? + +The `overlay2` storage driver. + +### Can an installation where `docker info` says that I’m using devicemapper with a loopback file work? + +No. This is an installation that Docker provides as sample and is not supported by Terraform Enterprise due to the significant instability in it. Docker themselves [do not suggest using this mode](https://docs.docker.com/storage/storagedriver/device-mapper-driver/#configure-loop-lvm-mode-for-testing). + +### How do I know if an installation is in devicemapper loopback mode? + +Run the command `docker info | grep dev/loop`. If there is any output, you’re in devicemapper loopback mode. Docker may also print warning about loopback mode when you run the above command, which is another indicator. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/rhel-requirements.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/rhel-requirements.mdx new file mode 100644 index 0000000000..6b5d284b0a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/rhel-requirements.mdx @@ -0,0 +1,40 @@ +--- +page_title: RHEL Requirements - Installation - Terraform Enterprise +description: >- + Learn about the requirements for installing Terraform Enterprise on RedHat Enterprise Linux. +--- + +# RHEL Requirements for Terraform Enterprise + +When installing Terraform Enterprise on RedHat Enterprise Linux (RHEL), ensure you meet the following requirements. + +## Install Requirements + +- A [supported version](/terraform/enterprise/deploy/replicated/requirements/os-specific/supported-os) of RedHat Enterprise Linux. +- A [supported Docker Engine](/terraform/enterprise/deploy/replicated/requirements/docker_engine) configuration. + +## FAQ + +### When I run the installer, it allows me to download and install Docker CE on RedHat. Can I use that? + +Yes, this is the recommended option. Docker CE is compatible with Terraform Enterprise, and tested nightly. It is not directly supported by RedHat, but there is a robust [open source community](https://www.docker.com/support/). + + +### How can I prevent accidental upgrades of Docker? + +To pin the version of Docker and prevent an inadvertent upgrade, follow [this guide](https://access.redhat.com/solutions/98873) from RedHat. + +For Red Hat Enterprise Linux v8 please use Docker CE for CentOS. This is tested nightly and ahead of each release of Terraform Enterprise. + + +### Which storage driver should I use? + +The `overlay2` storage driver. + +### Can an installation where `docker info` says that I’m using devicemapper with a loopback file work? + +No. This is an installation that docker provides as sample and is not supported by Terraform Enterprise due to the significant instability in it. Docker themselves do not suggest using [this mode](https://docs.docker.com/storage/storagedriver/device-mapper-driver/#configure-loop-lvm-mode-for-testing). + +### How do I know if an installation is in devicemapper loopback mode? + +Run the command `sudo docker info | grep dev/loop`. If there is any output, you’re in devicemapper loopback mode. Docker may also print warning about loopback mode when you run the above command, which is another indicator. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/supported-os.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/supported-os.mdx new file mode 100644 index 0000000000..01f2261e1f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/replicated/requirements/os-specific/supported-os.mdx @@ -0,0 +1,33 @@ +--- +page_title: Supported Operating Systems - Requirements - Terraform Enterprise +description: >- + Terraform Enterprise can run on Debian, Ubuntu, CentOS, and several types of + Linux (RedHat, Amazon, and Oracle). +--- + +# Supported Operating Systems + +Terraform Enterprise currently supports running under the following operating systems: + +- Debian 11 +- Ubuntu 20.04 / 22.04 / 24.04 +- Red Hat Enterprise Linux 8.4 - 8.8 ([RedHat Linux Requirements](/terraform/enterprise/replicated/requirements/os-specific/rhel-requirements)) +- CentOS 8.4 ([CentOS Requirements](/terraform/enterprise/replicated/requirements/os-specific/centos-requirements)) +- Amazon Linux 2.0 / 2023 +- Oracle Linux 8.4 + +## SELinux + +Terraform Enterprise supports SELinux running in enforcing mode when certain requirements are met. These requirements vary depending on the type of Terraform Enterprise installation. + +For External Services installations, you must install the latest version of the `container-selinux` package. + +For Mounted Disk installations, you must: + +- Install the latest version of the `container-selinux` package. +- Add the `container_file_t` type to the SELinux context for the mounted disk path and its subdirectories. The commands below update the mounted disk path `/opt/tfe` and its subdirectories to use the correct SELinux context. + + ``` + semanage fcontext -a -t container_file_t "/opt/tfe(/.*)?" + restorecon -R /opt/tfe + ``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/contact-support.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/contact-support.mdx new file mode 100644 index 0000000000..10c2be7a6e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/contact-support.mdx @@ -0,0 +1,61 @@ +--- +page_title: Get support for Terraform Enterprise +description: Learn to how to get HashiCorp support for Terraform Enterprise. +--- + +# Get support for Terraform Enterprise + +If some aspect of Terraform Enterprise is not working as +expected, reach out to support for help. + +## Open a ticket + +If you need assistance or want to submit a feature request, visit the [HashiCorp support center](https://support.hashicorp.com/hc/en-us) and open a ticket. + +## Diagnostics + +For most technical issues, HashiCorp support will ask you to include diagnostic +information in your support request. To ensure the required information is included, +Terraform Enterprise can automatically generate a support bundle including logs and configuration details. + +### Support bundles + +Provide the following information with any support requests: + - Deployment runtime, such as Docker or Kubernetes. + - Deployment cloud service, such as AWS, AzureRM, GCP, or your local data center. + - Operational mode, such as `disk` or `external` + - Your [support bundle](/terraform/enterprise/deploy/troubleshoot/perform-diagnostics#generate-a-support-bundle) + +#### Replicated deployments + +If Terraform Enterprise is deployed to the legacy Replicated runtime, you can access diagnostic information in the installer dashboard or on port `8800` of your installation. + +The installer dashboard is disabled for Replicated deployments in [`active-active` mode](/terraform/enterprise/reference/configuration#active-active). Instead, you can generate and save support bundles to your configured object storage location by executing the `tfe-admin support-bundle` command on a node instance from every node in the cluster. + +On the dashboard, click on the Support tab: + +![Terraform Enterprise Dashboard Top](/img/docs/tfe-dashboard.png) + +On the next page, click **Download Support Bundle** to download the support bundle directly to your web browser. + +![Terraform Enterprise Support](/img/docs/tfe-support.png) + +## Uploading the Support Bundle + +Once you have downloaded your support bundle, please use a secure method to upload it to HashiCorp support. + +### Existing Customers + +Attach the bundle to your support ticket. + +If possible, use the SendSafely integration available in the [HashiCorp support portal](https://support.hashicorp.com/hc/en-us). SendSafely lets you upload large file. + +If you are unable to use the integration in the portal, upload the bundle directly to `https://hashicorp.sendsafely.com/u/ptfe-support-bundles`. + +### Pre-Sales Customers + +If you are in the pre-sales phase, please upload support bundle files directly to `https://hashicorp.sendsafely.com/u/ptfe-support-bundles`. + +### About the Bundle + +The support bundle contains logging and telemetry data from various components in Terraform Enterprise. It may also include log data from Terraform builds you have executed on your Terraform Enterprise installation. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/error-messages.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/error-messages.mdx new file mode 100644 index 0000000000..c798086065 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/error-messages.mdx @@ -0,0 +1,133 @@ +--- +page_title: Troubleshooting common application errors +description: Learn about the errors Terraform Enterprise may report if your deployment is misconfigured and how to resolve them. +--- + +# Troubleshooting common application errors + +This topic describes the errors Terraform Enterprise may report if your deployment is misconfigured and how to resolve them. + +## Kubernetes Fails to Pull Image + +### Symptom + +Kubernetes pods are failing to pull the container image with a `BackOff` error. + +### Signals + +`kubectl describe pod` is stuck in the `Waiting` state with the `ErrImagePull` +reason. + +```sh +$ kubectl describe pod terraform-enterprise-7f649f6598-2k79b +... +Containers: + terraform-enterprise: + State: Waiting + Reason: ErrImagePull +... +``` + +### Solution + +Update the image pull policy for the deployment to `always`. + +## Empty S3 static credentials + +### Symptom + +Application fails to start. + +### Signals + +Logs show the following S3 prefix detection error. + +```sh +2023-05-10T23:38:18.100Z [ERROR] terraform-enterprise: startup: error="failed detecting s3 prefix: could not list objects: operation error S3: ListObjectsV2, failed to sign request: failed to retrieve credentials: failed to refresh cached credentials, static credentials are empty" +``` + +### Solution + +Set `TFE_OBJECT_STORAGE_S3_USE_INSTANCE_PROFILE` to `true` when using IAM auth +for S3. + +## Unknown certificate with VCS integration + +### Symptom + +You cannot configure a VCS connection within Terraform Enterprise. + +### Signals + +Setting up VCS fails with `unknown certificate issuer` error. + +### Solution + +Include the CA certificate for your VCS server in the CA Bundle. Ensure the +`TFE_TLS_CA_BUNDLE_FILE` is set to a path pointing to your CA bundle. + +## Unknown certificate with failing Terraform runs + +### Symptom + +Terraform plans and applies fail. + +### Signals + +Logs for task worker and archivist show an x509 error. + +### Solution + +Include the CA certificates for all hosts that Terraform must communicate with, +including your Terraform Enterprise server itself, in the CA Bundle. Ensure the +`TFE_TLS_CA_BUNDLE_FILE` is set to a path pointing to your CA bundle. + +## Unable to fetch Terraform binary + +### Symptom + +Terraform plans and applies fail with `failed downloading terraform`. + +### Signals + +Terraform run logs contain. + +```sh +Operation failed: failed fetching Terraform: failed downloading terraform: failed downloading "https://releases.hashicorp.com/terraform/1.3.2/terraform_1.3.2_linux_amd64.zip": GET https://releases.hashicorp.com/terraform/1.3.2/terraform_1.3.2_linux_amd64.zip giving up after 5 attempt(s): failed making temp file: open /tmp/terraform/8c23e18ed1846a552fc22ed5ee80eec9.download-67d5219a-aa5c-cd41-3262-2b9d57c1bfe2: read-only file system +``` + +### Solution + +Ensure the `TFE_DISK_CACHE_PATH` location is properly backed by a writable +volume. + +## Unable to write to database after a failover + +### Symptom + +If Terraform Enteprise is connected to a PostgreSQL database cluster, you may experience issues after a failover. + +### Signals + +The Vault logs contain the following entry: + + + + +cannot execute INSERT in a read-only transaction (SQLSTATE 25006) + + + + +### Solutions + +You may need to manually address issues after a failover to return to functionality. The Vault process may still be connected to a read-only instance if the affected instance can not process runs. Perform the following actions to resolve this issue: + +1. Restart Terraform Enterprise. + +1. Reopen sealed Vault processes. If the Vault process seals before the failover resolves, either restart Terraform Enterprise or restart the Vault process. Use the following command to restart the Vault process: + + ```sh + $ supervisorctl restart tfe:vault + ``` + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/index.mdx new file mode 100644 index 0000000000..11ed677ed5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/index.mdx @@ -0,0 +1,16 @@ +--- +page_title: Troubleshooting Terraform Enterprise +description: Use Terraform Enterprise logs and error messages to troubleshoot and debug errors. +--- + +# Troubleshooting overview + +This topic provides overview information about the troubleshooting tasks you can perform and the debugging information available through Terraform Enterprise interfaces to help your resolve errors with your deployment. + +## Workflows + +You can perform the following actions to troubleshoot your Terraform Enterprise deployment: + +1. [Contact HashiCorp support](/terraform/enterprise/deploy/troubleshoot/contact-support) and provide a support bundle to get help from the HashiCorp support team. +1. [Perform diagnistics](/terraform/enterprise/deploy/troubleshoot/perform-diagnostics), such as checking service health status and logs and enabling debug mode on Kubernetes. +1. Refer to the [error messages reference](/terraform/enterprise/deploy/troubleshoot/error-messages) for information about the errors Terraform Enterprise prints and steps to resolve them. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/perform-diagnostics.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/perform-diagnostics.mdx new file mode 100644 index 0000000000..f45c4c0c95 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/deploy/troubleshoot/perform-diagnostics.mdx @@ -0,0 +1,122 @@ +--- +page_title: Perform diagnostics on your Terraform Enterprise deployment +description: >- + Instructions for diagnosing problems with your Terraform Enterprise deployment. +--- + +# Perform diagnostics on your Terraform Enterprise deployment + +This topic provides instructions on how to perform diagnostic tasks to identify and resolve errors with your Terraform Enterprise deployment. + +## Run a health check + +Terraform Enterprise provides a `/_health_check` endpoint on the instance. If +Terraform Enterprise is up, the health check will return a `200 OK`. + +The `/_health_check` endpoint operates in 2 modes: + +- Full check +- Minimal check + +With a full check, the service will attempt to verify the status of internal +components and PostgreSQL, in contrast to a minimal check which returns `200 +OK` automatically after a successful check. + +The endpoint's default behavior is to perform a full check during startup of +the instance, and minimal checks after Terraform Enterprise is active and +running. + +To force a full check, include the additional query parameter `?full=1`. This +parameter causes every call to make requests to internal components and +PostgreSQL, increasing system load and latency. Use it sparingly. + +## Generate a support bundle + +A support bundle is a collection of logs and other information about your +installation that you can then send to HashiCorp Support for further +troubleshooting. + +You can generate a support bundle using the `tfectl support bundle` command. +Refer to [Support bundle](/terraform/enterprise/deploy/reference/cli#support-bundle) +in the CLI reference for additional information. + +### Support bundle contents + +Support bundles contain the following information: + +- Logs for all Terraform Enterprise services. +- License information for the installation. +- The Terraform Enterprise environment configuration with redacted secrets. +- Additional diagnostic information about the container, such as the contents + of `/etc/hosts`, disk and memory usage, and network configuration. + +Logs are available within the bundle under the `host` directory. All other +information is available within the `results.json` file located at the root of +the bundle. + +## Check service status + +To check the status of the services, execute the following command within +Terraform Enterprise container. + +```bash +$ supervisorctl status +``` + +Terraform Enterprise lists all services and their status in the console. Refer to the [Terraform Enterprise services reference](/terraform/enterprise/deploy/reference/services) for information about each service. + +```sh +$ supervisorctl status + +logs RUNNING pid 39, uptime 1:38:49 +postgres RUNNING pid 103, uptime 1:38:48 +redis RUNNING pid 77, uptime 1:38:49 +tfe:archivist RUNNING pid 199, uptime 1:38:46 +tfe:atlas RUNNING pid 200, uptime 1:38:46 +tfe:atlas-ui RUNNING pid 201, uptime 1:38:46 +tfe:backup-restore RUNNING pid 203, uptime 1:38:46 +tfe:licensing RUNNING pid 205, uptime 1:38:46 +tfe:metrics RUNNING pid 211, uptime 1:38:46 +tfe:nginx RUNNING pid 215, uptime 1:38:46 +tfe:outbound-http-proxy RUNNING pid 220, uptime 1:38:46 +tfe:sidekiq RUNNING pid 238, uptime 1:38:46 +tfe:slug-ingress RUNNING pid 248, uptime 1:38:46 +tfe:task-worker RUNNING pid 257, uptime 1:38:46 +tfe:terraform-registry-api RUNNING pid 265, uptime 1:38:46 +tfe:terraform-registry-worker RUNNING pid 280, uptime 1:38:46 +tfe:terraform-state-parser RUNNING pid 291, uptime 1:38:46 +tfe:tfe-health-check RUNNING pid 298, uptime 1:38:46 +tfe:vault RUNNING pid 309, uptime 1:38:46 +tfe-next RUNNING pid 40, uptime 1:38:49 +``` + +## Inspect logs + +To inspect the logs for a particular service, execute the following command +within the Terraform Enterprise container where `SERVICE_NAME` is the name of a +Terraform Enterprise service. + +```sh +$ cat /var/log/terraform-enterprise/SERVICE_NAME.log +``` + +For example, we can see why `tfe:licensing` exited. + +```sh +$ cat /var/log/terraform-enterprise/licensing.log +{"@level":"info","@message":"initializing database","@module":"tfe-licensing","@timestamp":"2023-05-10T20:46:26.379084Z"} +{"@level":"error","@message":"error opening database connection","@module":"tfe-licensing","@timestamp":"2023-05-10T20:46:26.399064Z","error":"failed to connect to `host=/var/run/postgresql user=terraform-enterprise database=`: server error (FATAL: role \"terraform-enterprise\" does not exist (SQLSTATE 28000))"} +``` + +## Run Kubernetes in debug mode + +Terraform Enterprise dispatches plans and applies via jobs when running inside Kubernetes. These jobs are removed immediately +after their execution, which can make it hard to understand if a job failed due to cluster-specific errors. + +To make troubleshooting easier in these scenarios, it is possible to keep the kubernetes jobs alive for a limited period of time, +after which they will get garbage collected by the cluster. To enable this, provide the following environment variables to +the deployment, either via the `env.variables` entry in the `values.yaml` override, or via the `ConfigMap` attached to the +deployment holding all of the environment variables. + +- `TFE_RUN_PIPELINE_KUBERNETES_DEBUG_ENABLED`. Boolean flag to enable debug mode, set to `true`. +- `TFE_RUN_PIPELINE_KUBERNETES_DEBUG_JOBS_TTL`. (Optional) time in seconds after which the jobs will get deleted; default is `86400`. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/index.mdx new file mode 100644 index 0000000000..0a1308d452 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/index.mdx @@ -0,0 +1,21 @@ +--- +page_title: Terraform Enterprise +description: >- + Terraform Enterprise is a self-hosted instance of HCP Terraform with + features like audit logging and SAML single sign-on. +--- + +# Terraform Enterprise + +Terraform Enterprise is HashiCorp's self-hosted distribution of [HCP Terraform](/terraform/cloud-docs). Terraform Enterprise offers a private instance of HCP Terraform application, with no resource limits and additional enterprise-grade architectural features like audit logging and SAML single sign-on. + +HCP Terraform and Terraform Enterprise are different distributions of the same application. When this documentation refers to HCP Terraform, the information applies to Terraform Enterprise unless specifically stated otherwise. + +-> **Introducing HCP Terraform**: Effective April 22, 2024, Terraform Cloud is now HCP Terraform. To learn more about this name change, refer to [Introducing the Infrastructure Cloud](https://www.hashicorp.com/blog/introducing-the-infrastructure-cloud). + +Before mid-2019, we referred to all distributions of HCP Terraform as Terraform Enterprise, and the self-hosted distribution as Private Terraform Enterprise (PTFE). These older names sometimes appear in supporting tools, like the [`tfe` Terraform provider](https://registry.terraform.io/providers/hashicorp/tfe/latest), which you can also use with HCP Terraform. + + +## Deploying Terraform Enterprise + +The [installation](/terraform/enterprise/deploy) and [administration](/terraform/enterprise/application-administration) instructions are for customers who feel confident that they can successfully deploy Terraform Enterprise on their own. If you are unsure, or have questions, please talk to your Solutions Engineer (pre-sales, POC or trial) or Customer Success Manager (existing customers). If you have read the documentation and are ready to schedule your install, please inform your Sales Engineer (pre-sales, POC or trial) or Customer Success Manager (existing customers) of your install time window so they can make sure they are available if necessary. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/aws-service-catalog/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/aws-service-catalog/index.mdx new file mode 100644 index 0000000000..e06a14e929 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/aws-service-catalog/index.mdx @@ -0,0 +1,27 @@ +--- +page_title: Terraform Enterprise for AWS Service Catalog overview +description: >- + Terraform Enterprise for AWS Service Catalog lets you provision infrastructure + with HCP Terraform inside AWS Service Catalog. +source: terraform-docs-common +--- + +# HCP Terraform for AWS Service Catalog overview + +This integration allows administrators to curate a portfolio of pre-approved Terraform configurations on AWS Service Catalog. This enables end users like engineers, database administrators, and data scientists to deploy these Terraform configurations with a single action from the AWS interface. By combining HCP Terraform with AWS Service Catalog, we’re combining a self-service interface that many customers are familiar with, AWS Service Catalog, with the existing workflows and policy guardrails of HCP Terraform. + + + +@include 'tfc-package-callouts/aws-service-catalog.mdx' + + + +## Installation & Configuration + +To start using this integration, you'll need to install the [AWS Service Catalog Engine for Terraform Cloud](https://github.com/hashicorp/aws-service-catalog-engine-for-tfc) provided by HashiCorp on GitHub by following the [setup instructions](https://github.com/hashicorp/aws-service-catalog-engine-for-tfc#getting-started) provided in the README. If you run into any setup troubles along the way, the README also includes [troubleshooting steps](https://github.com/hashicorp/aws-service-catalog-engine-for-tfc#troubleshooting) that should help resolve common issues that you may encounter. + +With the engine installed, the necessary code and infrastructure to integrate the HCP Terraform engine with AWS Service Catalog will automatically be configured. The setup can be completed in just a few minutes, and it only needs to be done once. Once the setup is complete, you can immediately start using AWS Service Catalog to develop and manage AWS Service Catalog products, and make them accessible to your end users across all your accounts. + +## Usage + +You can access this new feature through the AWS Service Catalog console in any AWS regions where AWS Service Catalog is supported and follow the AWS Service Catalog Administrator Guide to [create your first Terraform product](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/getstarted-product-Terraform.html). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/index.mdx new file mode 100644 index 0000000000..dc8851bfba --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/index.mdx @@ -0,0 +1,26 @@ +--- +page_title: Integrations overview for Terraform Enterprise +description: >- + Use Terraform Enterprise integrations to connect HCP Terraform with + third-party platforms and systems. +source: terraform-docs-common +--- + +# Overview + +The HCP Terraform ecosystem features a variety of integrations to let HCP +Terraform connect with third-party systems and platforms. The following list +contains HashiCorp's official HCP Terraform integrations, which use HCP +Terraform's native APIs: + +- The [HCP Terraform Operator for Kubernetes](/terraform/enterprise/integrations/kubernetes) integration can manage HCP Terraform resources with Kubernetes custom resources. +- The [ServiceNow Service Catalog for Terraform](/terraform/enterprise/integrations/service-now/service-catalog-terraform) lets you provision self-serve infrastructure using ServiceNow. +- The [ServiceNow Service Graph Connector for Terraform](/terraform/enterprise/integrations/service-now/service-graph) integration lets you securely import HCP Terraform resources into your ServiceNow instance. +- The [HCP Terraform for Splunk](/terraform/enterprise/integrations/splunk) integration lets you pull HCP Terraform logs into Splunk. +- The [HCP Terraform for AWS Service Catalog](/terraform/enterprise/integrations/aws-service-catalog) integration lets you create pre-approved Terraform configurations on the AWS Service Catalog. + +If the platform you want to integrate HCP Terraform with does not have an +official integration, you can build a custom run task to integrate with a tool +of your choice. Run tasks can access plan details, display custom messages in +the run pipeline, and prevent runs from applying. Learn more about [Run +tasks](/terraform/enterprise/integrations/run-tasks). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/annotations-and-labels.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/annotations-and-labels.mdx new file mode 100644 index 0000000000..e38bdb08c1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/annotations-and-labels.mdx @@ -0,0 +1,26 @@ +--- +page_title: Terraform Enterprise Operator for Kubernetes annotations and labels +description: >- + Use annotations and labels with the Terraform Enterprise Operator for + Kubernetes to manage Terraform runs. +source: terraform-docs-common +--- + +# HCP Terraform Operator for Kubernetes annotations and labels + +This topic contains reference information about the annotations and labels the HCP Terraform and Terraform Enterprise operators use for Kubernetes. + +## Annotations + +| Annotation key | Target resources | Possible values | Description | +| -------------------------------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `workspace.app.terraform.io/run-new` | Workspace | `"true"` | Set this annotation to `"true"` to trigger a new run. Example: `kubectl annotate workspace workspace.app.terraform.io/run-new="true"`. | +| `workspace.app.terraform.io/run-type` | Workspace | `plan`, `apply`, `refresh` | Specifies the run type. Changing this annotation does not start a new run. Refer to [Run Modes and Options](/terraform/enterprise/run/modes-and-options) for more information. Defaults to `"plan"`. | +| `workspace.app.terraform.io/run-terraform-version` | Workspace | Any valid Terraform version | Specifies the Terraform version to use. Changing this annotation does not start a new run. Only valid when the annotation `workspace.app.terraform.io/run-type` is set to `plan`. Defaults to the Workspace version. | + +## Labels + +| Label key | Target resources | Possible values | Description | +| -------------------------------------- | ---------------- | ------------------------ | ------------------------------------------------------------------------------------------- | +| `agentpool.app.terraform.io/pool-name` | Pod[Agent] | Any valid AgentPool name | Associate the resource with a specific agent pool by specifying the name of the agent pool. | +| `agentpool.app.terraform.io/pool-id` | Pod[Agent] | Any valid AgentPool ID | Associate the resource with a specific agent pool by specifying the ID of the agent pool. | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/api-reference.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/api-reference.mdx new file mode 100644 index 0000000000..1c1be52818 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/api-reference.mdx @@ -0,0 +1,796 @@ +--- +page_title: Terraform Enterprise Operator for Kubernetes API reference +description: >- + Use the Terraform Enterprise Operator for Kubernetes API to manage HCP + Terraform workspaces, modules, and agent pools. +source: terraform-docs-common +--- + +# HCP Terraform Operator for Kubernetes API reference + +## Packages + +- [app.terraform.io/v1alpha2](#appterraformiov1alpha2) + +## app.terraform.io/v1alpha2 + +Package v1alpha2 contains API Schema definitions for the app v1alpha2 API group. + +### Resource Types + +- [AgentPool](#agentpool) +- [Module](#module) +- [Project](#project) +- [Workspace](#workspace) + +#### AgentDeployment + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) + +| Field | Description | +| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `replicas` _integer_ | | +| `spec` _[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podspec-v1-core)_ | | +| `annotations` _object (keys:string, values:string)_ | The annotations that the operator will apply to the pod template in the deployment. | +| `labels` _object (keys:string, values:string)_ | The labels that the operator will apply to the pod template in the deployment. | + +#### AgentDeploymentAutoscaling + +AgentDeploymentAutoscaling allows you to configure the operator to scale the deployment for an AgentPool up and down to meet demand. + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) + +| Field | Description | +| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `maxReplicas` _integer_ | MaxReplicas is the maximum number of replicas for the Agent deployment. | +| `minReplicas` _integer_ | MinReplicas is the minimum number of replicas for the Agent deployment. | +| `targetWorkspaces` _[TargetWorkspace](#targetworkspace)_ | TargetWorkspaces is a list of HCP Terraform Workspaces which the agent pool should scale up to meet demand. When this field is omitted the autoscaler will target all workspaces that are associated with the AgentPool. | +| `cooldownPeriodSeconds` _integer_ | CooldownPeriodSeconds is the time to wait between scaling events. Defaults to 300. | +| `cooldownPeriod` _[AgentDeploymentAutoscalingCooldownPeriod](#agentdeploymentautoscalingcooldownperiod)_ | CoolDownPeriod configures the period to wait between scaling up and scaling down | + +#### AgentDeploymentAutoscalingCooldownPeriod + +AgentDeploymentAutoscalingCooldownPeriod configures the period to wait between scaling up and scaling down, + +_Appears in:_ + +- [AgentDeploymentAutoscaling](#agentdeploymentautoscaling) + +| Field | Description | +| ---------------------------- | --------------------------------------------------------- | +| `scaleUpSeconds` _integer_ | ScaleUpSeconds is the time to wait before scaling up. | +| `scaleDownSeconds` _integer_ | ScaleDownSeconds is the time to wait before scaling down. | + +#### AgentDeploymentAutoscalingStatus + +AgentDeploymentAutoscalingStatus + +_Appears in:_ + +- [AgentPoolStatus](#agentpoolstatus) + +| Field | Description | +| -------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| `desiredReplicas` _integer_ | Desired number of agent replicas | +| `lastScalingEvent` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#time-v1-meta)_ | Last time the agent pool was scaled | + +#### AgentPool + +AgentPool manages HCP Terraform Agent Pools, HCP Terraform Agent Tokens and can perform HCP Terraform Agent scaling. + +More information: + +- [Manage agent pools](/terraform/cloud-docs/agents/agent-pools) +- [Agent API tokens](/terraform/enterprise/users-teams-organizations/api-tokens#agent-api-tokens) +- [HCP Terraform agents](/terraform/cloud-docs/agents) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `AgentPool` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[AgentPoolSpec](#agentpoolspec)_ | | + +#### AgentPoolSpec + +AgentPoolSpec defines the desired state of AgentPool. + +_Appears in:_ + +- [AgentPool](#agentpool) + +| Field | Description | +| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Agent Pool name. [More information](/terraform/cloud-docs/agents/agent-pools). | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `agentTokens` _[AgentToken](#agenttoken) array_ | List of the agent tokens to generate. | +| `agentDeployment` _[AgentDeployment](#agentdeployment)_ | Agent deployment settings | +| `autoscaling` _[AgentDeploymentAutoscaling](#agentdeploymentautoscaling)_ | Agent deployment settings | + +#### AgentToken + +Agent Token is a secret token that a HCP Terraform Agent is used to connect to the HCP Terraform Agent Pool. In `spec` only the field `Name` is allowed, the rest are used in `status`. + +More information: + +- [HCP Terraform agents](/terraform/cloud-docs/agents) + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) +- [AgentPoolStatus](#agentpoolstatus) + +| Field | Description | +| ---------------------- | ------------------------------------------------ | +| `name` _string_ | Agent Token name. | +| `id` _string_ | Agent Token ID. | +| `createdAt` _integer_ | Timestamp of when the agent token was created. | +| `lastUsedAt` _integer_ | Timestamp of when the agent token was last used. | + +#### ConfigurationVersionStatus + +A configuration version is a resource used to reference the uploaded configuration files. + +More information: + +- [Configuration versions API reference](/terraform/enterprise/api-docs/configuration-versions) +- [The API-driven run workflow](/terraform/enterprise/run/api) + +_Appears in:_ + +- [ModuleStatus](#modulestatus) + +| Field | Description | +| ------------- | ------------------------- | +| `id` _string_ | Configuration Version ID. | + +#### ConsumerWorkspace + +ConsumerWorkspace allows access to the state for specific workspaces within the same organization. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Remote state access controls](/terraform/enterprise/workspaces/state#remote-state-access-controls) + +_Appears in:_ + +- [RemoteStateSharing](#remotestatesharing) + +| Field | Description | +| --------------- | -------------------------------------------------------------- | +| `id` _string_ | Consumer Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` | +| `name` _string_ | Consumer Workspace name. | + +#### CustomPermissions + +Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. + +More information: + +- [Custom workspace permissions](/terraform/enterprise/users-teams-organizations/permissions#custom-workspace-permissions) + +_Appears in:_ + +- [TeamAccess](#teamaccess) + +| Field | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `runs` _string_ | Run access. Must be one of the following values: `apply`, `plan`, `read`. Default: `read`. | +| `runTasks` _boolean_ | Manage Workspace Run Tasks. Default: `false`. | +| `sentinel` _string_ | Download Sentinel mocks. Must be one of the following values: `none`, `read`. Default: `none`. | +| `stateVersions` _string_ | State access. Must be one of the following values: `none`, `read`, `read-outputs`, `write`. Default: `none`. | +| `variables` _string_ | Variable access. Must be one of the following values: `none`, `read`, `write`. Default: `none`. | +| `workspaceLocking` _boolean_ | Lock/unlock workspace. Default: `false`. | + +#### CustomProjectPermissions + +Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. + +More information: + +- [Custom project permissions](/terraform/enterprise/users-teams-organizations/permissions#custom-project-permissions) +- [General workspace permissions](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) + +_Appears in:_ + +- [ProjectTeamAccess](#projectteamaccess) + +| Field | Description | +| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `projectAccess` _[ProjectSettingsPermissionType](#projectsettingspermissiontype)_ | Project access. Must be one of the following values: `delete`, `read`, `update`. Default: `read`. | +| `teamManagement` _[ProjectTeamsPermissionType](#projectteamspermissiontype)_ | Team management. Must be one of the following values: `manage`, `none`, `read`. Default: `none`. | +| `createWorkspace` _boolean_ | Allow users to create workspaces in the project. This grants read access to all workspaces in the project. Default: `false`. | +| `deleteWorkspace` _boolean_ | Allows users to delete workspaces in the project. Default: `false`. | +| `moveWorkspace` _boolean_ | Allows users to move workspaces out of the project. A user must have this permission on both the source and destination project to successfully move a workspace from one project to another. Default: `false`. | +| `lockWorkspace` _boolean_ | Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to "local", users must have this permission to perform local CLI runs using the workspace's state. Default: `false`. | +| `runs` _[WorkspaceRunsPermissionType](#workspacerunspermissiontype)_ | Run access. Must be one of the following values: `apply`, `plan`, `read`. Default: `read`. | +| `runTasks` _boolean_ | Manage Workspace Run Tasks. Default: `false`. | +| `sentinelMocks` _[WorkspaceSentinelMocksPermissionType](#workspacesentinelmockspermissiontype)_ | Download Sentinel mocks. Must be one of the following values: `none`, `read`. Default: `none`. | +| `stateVersions` _[WorkspaceStateVersionsPermissionType](#workspacestateversionspermissiontype)_ | State access. Must be one of the following values: `none`, `read`, `read-outputs`, `write`. Default: `none`. | +| `variables` _[WorkspaceVariablesPermissionType](#workspacevariablespermissiontype)_ | Variable access. Must be one of the following values: `none`, `read`, `write`. Default: `none`. | + +#### DeletionPolicy + +_Underlying type:_ _string_ + +DeletionPolicy defines the strategy the Kubernetes operator uses when you delete a resource, either manually or by a system event. + +You must use one of the following values: + +- `retain`: When you delete the custom resource, the operator does not delete the workspace. +- `soft`: Attempts to delete the associated workspace only if it does not contain any managed resources. +- `destroy`: Executes a destroy operation to remove all resources managed by the associated workspace. Once the destruction of these resources is successful, the operator deletes the workspace, and then deletes the custom resource. +- `force`: Forcefully and immediately deletes the workspace and the custom resource. + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +#### Module + +Module implements API-driven Run Workflows. + +More information: + +- [The API-driven run workflow](/terraform/enterprise/run/api) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `Module` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[ModuleSpec](#modulespec)_ | | + +#### ModuleOutput + +Module outputs to store in ConfigMap(non-sensitive) or Secret(sensitive). + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| --------------------- | ----------------------------------------------------------------- | +| `name` _string_ | Output name must match with the module output. | +| `sensitive` _boolean_ | Specify whether or not the output is sensitive. Default: `false`. | + +#### ModuleSource + +Module source and version to execute. + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| ------------------ | ------------------------------------------------------------------------------------------- | +| `source` _string_ | Non local Terraform module source. [More information](/terraform/language/modules/sources). | +| `version` _string_ | Terraform module version. | + +#### ModuleSpec + +ModuleSpec defines the desired state of Module. + +_Appears in:_ + +- [Module](#module) + +| Field | Description | +| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `module` _[ModuleSource](#modulesource)_ | Module source and version to execute. | +| `workspace` _[ModuleWorkspace](#moduleworkspace)_ | Workspace to execute the module. | +| `name` _string_ | Name of the module that will be uploaded and executed. Default: `this`. | +| `variables` _[ModuleVariable](#modulevariable) array_ | Variables to pass to the module, they must exist in the Workspace. | +| `outputs` _[ModuleOutput](#moduleoutput) array_ | Module outputs to store in ConfigMap(non-sensitive) or Secret(sensitive). | +| `destroyOnDeletion` _boolean_ | Specify whether or not to execute a Destroy run when the object is deleted from the Kubernetes. Default: `false`. | +| `restartedAt` _string_ | Allows executing a new Run without changing any Workspace or Module attributes. Example: ``kubectl patch KIND NAME --type=merge --patch '{"spec": \{"restartedAt": "'\`date -u -Iseconds\`'"\}\}'`` | + +#### ModuleVariable + +Variables to pass to the module. + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| --------------- | ------------------------------------------ | +| `name` _string_ | Variable name must exist in the Workspace. | + +#### ModuleWorkspace + +Workspace to execute the module. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| --------------- | ------------------------------------------------------------ | +| `id` _string_ | Module Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` | +| `name` _string_ | Module Workspace Name. | + +#### Notification + +Notifications allow you to send messages to other applications based on run and workspace events. + +More information: + +- [Workspace notifications](/terraform/enterprise/workspaces/settings/notifications) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Notification name. | +| `type` _[NotificationDestinationType](#notificationdestinationtype)_ | The type of the notification. Must be one of the following values: `email`, `generic`, `microsoft-teams`, `slack`. | +| `enabled` _boolean_ | Whether the notification configuration should be enabled or not. Default: `true`. | +| `token` _string_ | The token of the notification. | +| `triggers` _[NotificationTrigger](#notificationtrigger) array_ | The list of run events that will trigger notifications. Trigger represents the different TFC notifications that can be sent as a run's progress transitions between different states. There are two categories of triggers: - Health Events: `assessment:check_failure`, `assessment:drifted`, `assessment:failed`. - Run Events: `run:applying`, `run:completed`, `run:created`, `run:errored`, `run:needs_attention`, `run:planning`. | +| `url` _string_ | The URL of the notification. Must match pattern: `^https?://.*` | +| `emailAddresses` _string array_ | The list of email addresses that will receive notification emails. It is only available for Terraform Enterprise users. It is not available in HCP Terraform. | +| `emailUsers` _string array_ | The list of users belonging to the organization that will receive notification emails. | + +#### NotificationTrigger + +_Underlying type:_ _string_ + +NotificationTrigger represents the different TFC notifications that can be sent as a run's progress transitions between different states. This must be aligned with go-tfe type `NotificationTriggerType`. + +Must be one of the following values: `run:applying`, `assessment:check_failure`, `run:completed`, `run:created`, `assessment:drifted`, `run:errored`, `assessment:failed`, `run:needs_attention`, `run:planning`. + +_Appears in:_ + +- [Notification](#notification) + +#### OutputStatus + +Outputs status. + +_Appears in:_ + +- [ModuleStatus](#modulestatus) + +| Field | Description | +| ---------------- | -------------------------------------------------- | +| `runID` _string_ | Run ID of the latest run that updated the outputs. | + +#### PlanStatus + +_Appears in:_ + +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| --------------------------- | ------------------------------------------------------- | +| `id` _string_ | Latest plan-only/speculative plan HCP Terraform run ID. | +| `terraformVersion` _string_ | The version of Terraform to use for this run. | + +#### Project + +Project manages HCP Terraform Projects. + +More information: + +- [Manage projects](/terraform/enterprise/projects/manage) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `Project` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[ProjectSpec](#projectspec)_ | | + +#### ProjectSpec + +ProjectSpec defines the desired state of Project. + +More information: + +- [Manage projects](/terraform/enterprise/workspaces/organize-workspaces-with-projects) + +_Appears in:_ + +- [Project](#project) + +| Field | Description | +| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `name` _string_ | Name of the Project. | +| `teamAccess` _[ProjectTeamAccess](#projectteamaccess) array_ | HCP Terraform's access model is team-based. In order to perform an action within a HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. You can assign project-specific permissions to teams. More information: [Manage projects](/terraform/enterprise/workspaces/organize-workspaces-with-projects#permissions) and [Project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions). | + +#### ProjectTeamAccess + +HCP Terraform's access model is team-based. In order to perform an action within a HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. You can assign project-specific permissions to teams. + +More information: + +- [Manage projects](/terraform/enterprise/workspaces/organize-workspaces-with-projects#permissions) +- [Project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) + +_Appears in:_ + +- [ProjectSpec](#projectspec) + +| Field | Description | +| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `team` _[Team](#team)_ | Team to grant access. [More information](/terraform/enterprise/users-teams-organizations/teams). | +| `access` _[TeamProjectAccessType](#teamprojectaccesstype)_ | There are two ways to choose which permissions a given team has on a project: fixed permission sets, and custom permissions. Must be one of the following values: `admin`, `custom`, `maintain`, `read`, `write`. More information: [Project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) and [General project permissions](/terraform/enterprise/users-teams-organizations/permissions#general-project-permissions). | +| `custom` _[CustomProjectPermissions](#customprojectpermissions)_ | Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. [More information](/terraform/enterprise/users-teams-organizations/permissions#custom-project-permissions). | + +#### RemoteStateSharing + +RemoteStateSharing allows remote state access between workspaces. By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. + +More information: + +- [Accessing state from other workspaces](/terraform/enterprise/workspaces/state#accessing-state-from-other-workspaces) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| `allWorkspaces` _boolean_ | Allow access to the state for all workspaces within the same organization. Default: `false`. | +| `workspaces` _[ConsumerWorkspace](#consumerworkspace) array_ | Allow access to the state for specific workspaces within the same organization. | + +#### RunStatus + +_Appears in:_ + +- [ModuleStatus](#modulestatus) +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| ------------------------------- | ------------------------------------------------------- | +| `id` _string_ | Current(both active and finished) HCP Terraform run ID. | +| `configurationVersion` _string_ | The configuration version of this run. | +| `outputRunID` _string_ | Run ID of the latest run that could update the outputs. | + +#### RunTrigger + +RunTrigger allows you to connect this workspace to one or more source workspaces. These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Run triggers](/terraform/enterprise/workspaces/settings/run-triggers) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ------------------------------------------------------------ | +| `id` _string_ | Source Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` | +| `name` _string_ | Source Workspace Name. | + +#### SSHKey + +SSH key used to clone Terraform modules. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Use SSH Keys for cloning modules](/terraform/enterprise/workspaces/settings/ssh-keys) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ------------------------------------------------------- | +| `id` _string_ | SSH key ID. Must match pattern: `^sshkey-[a-zA-Z0-9]+$` | +| `name` _string_ | SSH key name. | + +#### Tag + +_Underlying type:_ _string_ + +Tags allows you to correlate, organize, and even filter workspaces based on the assigned tags. + +Tags must be one or more characters; can include letters, numbers, colons, hyphens, and underscores; and must begin and end with a letter or number. + +Must match pattern: `^[A-Za-z0-9][A-Za-z0-9:_-]*$` + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +#### TargetWorkspace + +TargetWorkspace is the name or ID of the workspace you want autoscale against. + +_Appears in:_ + +- [AgentDeploymentAutoscaling](#agentdeploymentautoscaling) + +| Field | Description | +| ----------------------- | --------------------------------------------------------------------------------------- | +| `id` _string_ | Workspace ID | +| `name` _string_ | Workspace Name | +| `wildcardName` _string_ | Wildcard Name to match match workspace names using `*` on name suffix, prefix, or both. | + +#### Team + +Teams are groups of HCP Terraform users within an organization. If a user belongs to at least one team in an organization, they are considered a member of that organization. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Teams overview](/terraform/enterprise/users-teams-organizations/teams) + +_Appears in:_ + +- [ProjectTeamAccess](#projectteamaccess) +- [TeamAccess](#teamaccess) + +| Field | Description | +| --------------- | -------------------------------------------------- | +| `id` _string_ | Team ID. Must match pattern: `^team-[a-zA-Z0-9]+$` | +| `name` _string_ | Team name. | + +#### TeamAccess + +HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. When a workspace is created, only the owners team and teams with the "manage workspaces" permission can access it, with full admin permissions. These teams' access can't be removed from a workspace. + +More information: + +- [Manage access to workspaces](/terraform/enterprise/workspaces/settings/access) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `team` _[Team](#team)_ | Team to grant access. [More information](/terraform/enterprise/users-teams-organizations/teams). | +| `access` _string_ | There are two ways to choose which permissions a given team has on a workspace: fixed permission sets, and custom permissions. Must be one of the following values: `admin`, `custom`, `plan`, `read`, `write`. [More information](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). | +| `custom` _[CustomPermissions](#custompermissions)_ | Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. [More information](/terraform/enterprise/users-teams-organizations/permissions#custom-workspace-permissions). | + +#### Token + +Token refers to a Kubernetes Secret object within the same namespace as the Workspace object + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) +- [ModuleSpec](#modulespec) +- [ProjectSpec](#projectspec) +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | +| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | Selects a key of a secret in the workspace's namespace | + +#### ValueFrom + +ValueFrom source for the variable's value. Cannot be used if value is not empty. + +_Appears in:_ + +- [Variable](#variable) + +| Field | Description | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | +| `configMapKeyRef` _[ConfigMapKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#configmapkeyselector-v1-core)_ | Selects a key of a ConfigMap. | +| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | Selects a key of a Secret. | + +#### Variable + +Variables let you customize configurations, modify Terraform's behavior, and store information like provider credentials. + +More information: + +- [Workspace variables](/terraform/enterprise/workspaces/variables) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Name of the variable. | +| `description` _string_ | Description of the variable. | +| `hcl` _boolean_ | Parse this field as HashiCorp Configuration Language (HCL). This allows you to interpolate values at runtime. Default: `false`. | +| `sensitive` _boolean_ | Sensitive variables are never shown in the UI or API. They may appear in Terraform logs if your configuration is designed to output them. Default: `false`. | +| `value` _string_ | Value of the variable. | +| `valueFrom` _[ValueFrom](#valuefrom)_ | Source for the variable's value. Cannot be used if value is not empty. | + +#### VariableSetStatus + +_Appears in:_ + +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| --------------- | ----------- | +| `id` _string_ | | +| `name` _string_ | | + +#### VariableStatus + +_Appears in:_ + +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| -------------------- | --------------------------------------------------- | +| `name` _string_ | Name of the variable. | +| `id` _string_ | ID of the variable. | +| `versionID` _string_ | VersionID is a hash of the variable on the TFC end. | +| `valueID` _string_ | ValueID is a hash of the variable on the CRD end. | +| `category` _string_ | Category of the variable. | + +#### VersionControl + +VersionControl settings for the workspace's VCS repository, enabling the UI/VCS-driven run workflow. Omit this argument to utilize the CLI-driven and API-driven workflows, where runs are not driven by webhooks on your VCS provider. + +More information: + +- [UI and VCS-driven run workflow](/terraform/enterprise/run/ui) +- [Connect to VCS Providers](/terraform/enterprise/vcs) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `oAuthTokenID` _string_ | The VCS Connection (OAuth Connection + Token) to use. Must match pattern: `^ot-[a-zA-Z0-9]+$` | +| `repository` _string_ | A reference to your VCS repository in the format `/` where `` and `` refer to the organization and repository in your VCS provider. | +| `branch` _string_ | The repository branch that Run will execute from. This defaults to the repository's default branch (e.g. main). | +| `speculativePlans` _boolean_ | Whether this workspace allows automatic speculative plans on PR. Default: `true`. More information: [Speculative plans on pull requests](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) and [Speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). | + +#### Workspace + +Workspace manages HCP Terraform Workspaces. + +More information: + +- [Workspaces](/terraform/enterprise/workspaces) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `Workspace` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[WorkspaceSpec](#workspacespec)_ | | + +#### WorkspaceAgentPool + +AgentPool allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [HCP Terraform agents](/terraform/cloud-docs/agents) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | --------------------------------------------------------- | +| `id` _string_ | Agent Pool ID. Must match pattern: `^apool-[a-zA-Z0-9]+$` | +| `name` _string_ | Agent Pool name. | + +#### WorkspaceProject + +Projects let you organize your workspaces into groups. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Organize workspaces with projects](/terraform/tutorials/cloud/projects) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ---------------------------------------------------- | +| `id` _string_ | Project ID. Must match pattern: `^prj-[a-zA-Z0-9]+$` | +| `name` _string_ | Project name. | + +#### WorkspaceRunTask + +Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` _string_ | Run Task ID. Must match pattern: `^task-[a-zA-Z0-9]+$` | +| `name` _string_ | Run Task Name. | +| `enforcementLevel` _string_ | Run Task Enforcement Level. Can be one of `advisory` or `mandatory`. Default: `advisory`. Must be one of the following values: `advisory`, `mandatory` Default: `advisory`. | +| `stage` _string_ | Run Task Stage. Must be one of the following values: `pre_apply`, `pre_plan`, `post_plan`. Default: `post_plan`. | + +#### WorkspaceSpec + +WorkspaceSpec defines the desired state of Workspace. + +_Appears in:_ + +- [Workspace](#workspace) + +| Field | Description | +| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Workspace name. | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `applyMethod` _string_ | Define either change will be applied automatically(auto) or require an operator to confirm(manual). Must be one of the following values: `auto`, `manual`. Default: `manual`. [More information](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply). | +| `allowDestroyPlan` _boolean_ | Allows a destroy plan to be created and applied. Default: `true`. [More information](/terraform/enterprise/workspaces/settings#destruction-and-deletion). | +| `description` _string_ | Workspace description. | +| `agentPool` _[WorkspaceAgentPool](#workspaceagentpool)_ | HCP Terraform Agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. [More information](/terraform/cloud-docs/agents). | +| `executionMode` _string_ | Define where the Terraform code will be executed. Must be one of the following values: `agent`, `local`, `remote`. Default: `remote`. [More information](/terraform/enterprise/workspaces/settings#execution-mode). | +| `runTasks` _[WorkspaceRunTask](#workspaceruntask) array_ | Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. [More information](/terraform/enterprise/workspaces/settings/run-tasks). | +| `tags` _[Tag](#tag) array_ | Workspace tags are used to help identify and group together workspaces. Tags must be one or more characters; can include letters, numbers, colons, hyphens, and underscores; and must begin and end with a letter or number. | +| `teamAccess` _[TeamAccess](#teamaccess) array_ | HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. When a workspace is created, only the owners team and teams with the "manage workspaces" permission can access it, with full admin permissions. These teams' access can't be removed from a workspace. [More information](/terraform/enterprise/workspaces/settings/access). | +| `terraformVersion` _string_ | The version of Terraform to use for this workspace. If not specified, the latest available version will be used. Must match pattern: `^\\d\{1\}\\.\\d\{1,2\}\\.\\d\{1,2\}$` [More information](/terraform/enterprise/workspaces/settings#terraform-version) | +| `workingDirectory` _string_ | The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. [More information](/terraform/enterprise/workspaces/settings#terraform-working-directory) | +| `environmentVariables` _[Variable](#variable) array_ | Terraform Environment variables for all plans and applies in this workspace. Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key. More information: [Workspace variables](/terraform/enterprise/workspaces/variables) and [Environment variables](/terraform/enterprise/workspaces/variables#environment-variables). | +| `terraformVariables` _[Variable](#variable) array_ | Terraform variables for all plans and applies in this workspace. Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key. More information: [Workspace variables](/terraform/enterprise/workspaces/variables) and [Terraform variables](/terraform/enterprise/workspaces/variables#terraform-variables). | +| `remoteStateSharing` _[RemoteStateSharing](#remotestatesharing)_ | Remote state access between workspaces. By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. [More information](/terraform/enterprise/workspaces/state#accessing-state-from-other-workspaces). | +| `runTriggers` _[RunTrigger](#runtrigger) array_ | Run triggers allow you to connect this workspace to one or more source workspaces. These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces. [More information](/terraform/enterprise/workspaces/settings/run-triggers). | +| `versionControl` _[VersionControl](#versioncontrol)_ | Settings for the workspace's VCS repository, enabling the UI/VCS-driven run workflow. Omit this argument to utilize the CLI-driven and API-driven workflows, where runs are not driven by webhooks on your VCS provider. More information: [UI and VCS-driven run workflow](/terraform/enterprise/run/ui) and [Connect to VCS providers](/terraform/enterprise/vcs) | +| `sshKey` _[SSHKey](#sshkey)_ | SSH key used to clone Terraform modules. [More information](/terraform/enterprise/workspaces/settings/ssh-keys). | +| `notifications` _[Notification](#notification) array_ | Notifications allow you to send messages to other applications based on run and workspace events. [More information](/terraform/enterprise/workspaces/settings/notifications). | +| `project` _[WorkspaceProject](#workspaceproject)_ | Projects let you organize your workspaces into groups. Default: default organization project. [More information](/terraform/tutorials/cloud/projects). | +| `deletionPolicy` _[DeletionPolicy](#deletionpolicy)_ | The Deletion Policy specifies the behavior of the custom resource and its associated workspace when the custom resource is deleted. - `retain`: When you delete the custom resource, the operator does not delete the workspace. - `soft`: Attempts to delete the associated workspace only if it does not contain any managed resources. - `destroy`: Executes a destroy operation to remove all resources managed by the associated workspace. Once the destruction of these resources is successful, the operator deletes the workspace, and then deletes the custom resource. - `force`: Forcefully and immediately deletes the workspace and the custom resource. Default: `retain`. | +| `variableSets` _[WorkspaceVariableSet](#workspacevariableset) array_ | HCP Terraform variable sets let you reuse variables in an efficient and centralized way. [More information](/terraform/tutorials/cloud/cloud-multiple-variable-sets) | + +#### WorkspaceVariableSet + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` _string_ | ID of the variable set. Must match pattern: `varset-[a-zA-Z0-9]+$` [More information](/terraform/tutorials/cloud/cloud-multiple-variable-sets). | +| `name` _string_ | Name of the variable set. [More information](/terraform/tutorials/cloud/cloud-multiple-variable-sets). | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/index.mdx new file mode 100644 index 0000000000..0b3e18a397 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/index.mdx @@ -0,0 +1,220 @@ +--- +page_title: Terraform Enterprise Operator for Kubernetes overview +description: >- + The Terraform Enterprise Operator for Kubernetes allows you to provision + infrastructure directly from the Kubernetes control plane. +source: terraform-docs-common +--- + +# HCP Terraform Operator for Kubernetes overview + +The [HCP Terraform Operator for Kubernetes](https://github.com/hashicorp/hcp-terraform-operator) allows you to manage HCP Terraform resources with Kubernetes custom resources. You can provision infrastructure internal or external to your Kubernetes cluster directly from the Kubernetes control plane. + +The operator's CustomResourceDefinitions (CRD) let you dynamically create HCP Terraform workspaces with Terraform modules, populate workspace variables, and provision infrastructure with Terraform runs. + +## Key benefits + +The HCP Terraform Operator for Kubernetes v2 offers several improvements over v1: + +- **Flexible resource management**: The operator now features multiple custom resources, each with separate controllers for different HCP Terraform resources. This provides additional flexibility and the ability to manage more custom resources concurrently, significantly improving performance for large-scale deployments. + +- **Namespace management**: The `--namespace` option allows you to tailor the operator's watch scope to specific namespaces, which enables more fine-grained resource management. + +- **Configurable synchronization**: The `--sync-period` option allows you to configure the synchronization frequency between custom resources and HCP Terraform, ensuring timely updates and smoother operations. + +## Supported HCP Terraform features + +The HCP Terraform Operator for Kubernetes allows you to create agent pools, deploy modules, and manage workspaces through Kubernetes controllers. These controllers enable you to automate and manage HCP Terraform resources using custom resources in Kubernetes. + +### Agent pools + +Agent pools in HCP Terraform manage the execution environment for Terraform runs. The HCP Terraform Operator for Kubernetes allows you to create and manage agent pools as part of your Kubernetes infrastructure. + +The following example creates a new agent pool with the name `agent-pool-development` and generates an agent token with the name `token-red`. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: AgentPool +metadata: + name: my-agent-pool +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: agent-pool-development + agentTokens: + - name: token-red +``` + +The operator stores the `token-red` agent token in a Kubernetes secret named `my-agent-pool-token-red`. + +You can also enable agent autoscaling by providing a `.spec.autoscaling` configuration in your `AgentPool` specification. + + + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: AgentPool +metadata: + name: this +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: agent-pool-development + agentTokens: + - name: token-red + agentDeployment: + replicas: 1 + autoscaling: + targetWorkspaces: + - name: us-west-development + - id: ws-NUVHA9feCXzAmPHx + - wildcardName: eu-development-* + minReplicas: 1 + maxReplicas: 3 + cooldownPeriod: + scaleUpSeconds: 30 + scaleDownSeconds: 30 +``` + + + +In the above example, the operator ensures that at least one agent pod is continuously running and dynamically scales the number of pods up to a maximum of three based on the workload or resource demand. The operator then monitors resource demands by observing the load of the designated workspaces specified by the `name`, `id`, or `wildcardName` patterns. When the workload decreases, the operator downscales the number of agent pods. + +Refer to the [agent pool API reference](/terraform/enterprise/integrations/kubernetes/api-reference#agentpool) for the complete `AgentPool` specification. + +### Module + +The `Module` controller enforces an [API-driven Run workflow](/terraform/enterprise/run/api) and lets you deploy Terraform modules within workspaces. + +The following example deploys version `1.0.0` of the `hashicorp/module/random` module in the `workspace-name` workspace. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Module +metadata: + name: my-module +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + module: + source: hashicorp/module/random + version: 1.0.0 + workspace: + name: workspace-name + variables: + - name: string_length + outputs: + - name: random_string +``` + +The operator passes the workspace's `string_length` variable to the module and stores the `random_string` outputs as either a Kubernetes secret or a ConfigMap. If the workspace marks the output as `sensitive`, the operator stores the `random_string` as a Kubernetes secret; otherwise, the operator stores it as a ConfigMap. The variables must be accessible within the workspace as a workspace variable, workspace variable set, or project variable set. + +Refer to the [module API reference](/terraform/enterprise/integrations/kubernetes/api-reference#module) for the complete `Module` specification. + +### Project + +Projects let you organize your workspaces and scope access to workspace resources. The `Project` controller allows you to create, configure, and manage [projects](/terraform/tutorials/cloud/projects) directly from Kubernetes. + +The following example creates a new project named `testing`. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Project +metadata: + name: testing +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: project-demo +``` + +The `Project` controller allows you to manage team access [permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions). + +The following example creates a project named `testing` and grants the `qa` team admin access to the project. + + + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Project +metadata: + name: testing +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: project-demo + teamAccess: + - team: + name: qa + access: admin +``` + + + +Refer to the [project API reference](/terraform/enterprise/integrations/kubernetes/api-reference#project) for the complete `Project` specification. + +### Workspace + +HCP Terraform workspaces organize and manage Terraform configurations. The HCP Terraform Operator for Kubernetes allows you to create, configure, and manage workspaces directly from Kubernetes. + +The following example creates a new workspace named `us-west-development`, configured to use Terraform version `1.6.2`. This workspace has two variables, `nodes` and `rds-secret`. The variable `rds-secret` is treated as sensitive, and the operator reads the value for the variable from a Kubernetes secret named `us-west-development-secrets`. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Workspace +metadata: + name: us-west-development +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: us-west-development + description: US West development workspace + terraformVersion: 1.6.2 + applyMethod: auto + agentPool: + name: ap-us-west-development + terraformVariables: + - name: nodes + value: 2 + - name: rds-secret + sensitive: true + valueFrom: + secretKeyRef: + name: us-west-development-secrets + key: rds-secret + runTasks: + - name: rt-us-west-development + stage: pre_plan +``` + +In the above example, the `applyMethod` has the value of `auto`, so HCP Terraform automatically applies any changes to this workspace. The specification also configures the workspace to use the `ap-us-west-development` agent pool and run the `rt-us-west-development` run task at the `pre_plan` stage. + +The operator stores the value of the workspace outputs as Kubernetes secrets or ConfigMaps. If the outputs are marked as `sensitive`, they are stored as Kubernetes secrets, otherwise they are stored as ConfigMaps. + +-> **Note**: The operator rolls back any external modifications made to the workspace to match the state specified in the custom resource definition. + +Refer to the [workspace API reference](/terraform/enterprise/integrations/kubernetes/api-reference#workspace) for the complete `Workspace` specification. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/ops-v2-migration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/ops-v2-migration.mdx new file mode 100644 index 0000000000..49c8bc1272 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/ops-v2-migration.mdx @@ -0,0 +1,342 @@ +--- +page_title: Migrate to Terraform Enterprise Operator for Kubernetes v2 +description: >- + Learn how to upgrade the Terraform Kubernetes Operator from version 1 to + version 2. +source: terraform-docs-common +--- + +# Migrate to HCP Terraform Operator for Kubernetes v2 + +~> **Warning**: Version 1 of the HCP Terraform Operator for Kubernetes is **deprecated** and no longer maintained. If you are installing the operator for the first time, refer to [Set up the HCP Terraform Operator for Kubernetes](/terraform/enterprise/integrations/kubernetes/setup) for guidance. + +To upgrade the HCP Terraform Operator for Kubernetes from version 1 to the HCP Terraform Operator for Kubernetes (version 2), there is a one-time process that you need to complete. This process upgrades the operator to the newest version and migrate your custom resources. + +## Prerequisites + +The migration process requires the following tools to be installed locally: + +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) +- [Helm](https://helm.sh/docs/intro/install/) + +## Prepare for the upgrade + +Configure an environment variable named `RELEASE_NAMESPACE` with the value of the namespace that the Helm chart is installed in. + +```shell-session +$ export RELEASE_NAMESPACE= +``` + +Next, create an environment variable named `RELEASE_NAME` with the value of the name that you gave your installation for the Helm chart. + +```shell-session +$ export RELEASE_NAME= +``` + +Before you migrate to HCP Terraform Operator for Kubernetes v2, you must first update v1 of the operator to the latest version, including the custom resource definitions. + +```shell-session +$ helm upgrade --namespace ${RELEASE_NAMESPACE} ${RELEASE_NAME} hashicorp/terraform +``` + +Next, backup the workspace resources. + +```shell-session +$ kubectl get workspace --all-namespaces -o yaml > backup_tfc_operator_v1.yaml +``` + +## Manifest schema migration + +Version 2 of the HCP Terraform Operator for Kubernetes renames and moves many existing fields. When you migrate, you must update your specification to match version 2's field names. + +### Workspace controller + +The table below lists the field mapping of the `Workspace` controller between v1 and v2 of the operator. + +| Version 1 | Version 2 | Changes between versions | +| --------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion: app.terraform.io/v1alpha1` | `apiVersion: app.terraform.io/v1alpha2` | The `apiVersion` is now `v1alpha2`. | +| `kind: Workspace` | `kind: Workspace` | None. | +| `metadata` | `metadata` | None. | +| `spec.organization` | `spec.organization` | None. | +| `spec.secretsMountPath` | `spec.token.secretKeyRef` | In v2 the operator keeps the HCP Terraform access token in a Kubernetes Secret. | +| `spec.vcs` | `spec.versionControl` | Renamed the `vcs` field to `versionControl`. | +| `spec.vcs.token_id` | `spec.versionControl.oAuthTokenID` | Renamed the `token_id` field to `oAuthTokenID`. | +| `spec.vcs.repo_identifier` | `spec.versionControl.repository` | Renamed the `repo_identifier` field to `repository`. | +| `spec.vcs.branch` | `spec.versionControl.branch` | None. | +| `spec.vcs.ingress_submodules` | `spec.workingDirectory` | Moved. | +| `spec.variables.[*]` | `spec.environmentVariables.[*]` OR `spec.terraformVariables.[*]` | We split variables into two possible places. In v1's CRD, if `spec.variables.environmentVariable` was `true`, migrate those variables to `spec.environmentVariables`. If `false`, migrate those variables to `spec.terraformVariables`. | +| `spec.variables.[*]key` | `spec.environmentVariables.[*]name` OR `spec.terraformVariables.[*]name` | Renamed the `key` field as `name`. [Learn more](#workspace-variables). | +| `spec.variables.[*]value` | `spec.environmentVariables.[*]value` OR `spec.terraformVariables.[*]value` | [Learn more](#workspace-variables). | +| `spec.variables.[*]valueFrom` | `spec.environmentVariables.[*]valueFrom` OR `spec.terraformVariables.[*]valueFrom` | [Learn more](#workspace-variables). | +| `spec.variables.[*]hcl` | `spec.environmentVariables.[*]hcl` OR `spec.terraformVariables.[*]hcl` | [Learn more](#workspace-variables). | +| `spec.variables.sensitive` | `spec.environmentVariables.[*]sensitive` OR `spec.terraformVariables.[*]sensitive` | [Learn more](#workspace-variables). | +| `spec.variables.environmentVariable` | N/A | Removed, variables are split between `spec.environmentVariables` and `spec.terraformVariables`. | +| `spec.runTriggers.[*]` | `spec.runTriggers.[*]` | None. | +| `spec.runTriggers.[*].sourceableName` | `spec.runTriggers.[*].name` | The `sourceableName` field is now `name`. | +| `spec.sshKeyID` | `spec.sshKey.id` | Moved the `sshKeyID` to `spec.sshKey.id`. | +| `spec.outputs` | N/A | Removed. | +| `spec.terraformVersion` | `spec.terraformVersion` | None. | +| `spec.notifications.[*]` | `spec.notifications.[*]` | None. | +| `spec.notifications.[*].type` | `spec.notifications.[*].type` | None. | +| `spec.notifications.[*].enabled` | `spec.notifications.[*].enabled` | None. | +| `spec.notifications.[*].name` | `spec.notifications.[*].name` | None. | +| `spec.notifications.[*].url` | `spec.notifications.[*].url` | None. | +| `spec.notifications.[*].token` | `spec.notifications.[*].token` | None. | +| `spec.notifications.[*].triggers.[*]` | `spec.notifications.[*].triggers.[*]` | None. | +| `spec.notifications.[*].recipients.[*]` | `spec.notifications.[*].emailAddresses.[*]` | Renamed the `recipients` field to `emailAddresses`. | +| `spec.notifications.[*].users.[*]` | `spec.notifications.[*].emailUsers.[*]` | Renamed the `users` field to `emailUsers`. | +| `spec.omitNamespacePrefix` | N/A | Removed. In v1 `spec.omitNamespacePrefix` is a boolean field that affects how the operator generates a workspace name. In v2, you must explicitly set workspace names in `spec.name`. | +| `spec.agentPoolID` | `spec.agentPool.id` | Moved the `agentPoolID` field to `spec.agentPool.id`. | +| `spec.agentPoolName` | `spec.agentPool.name` | Moved the `agentPoolName` field to `spec.agentPool.name`. | +| `spec.module` | N/A | Removed. You now configure modules with a separate `Module` CRD. [Learn more](#module-controller). | + +Below is an example of configuring a variable in v1 of the operator. + + + +```yaml +apiVersion: app.terraform.io/v1alpha1 +kind: Workspace +metadata: + name: migration + spec: + variables: + - key: username + value: "user" + hcl: true + sensitive: false + environmentVariable: false + - key: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false + environmentVariable: true +``` + + + +In v2 of the operator, you must configure Terraform variables in `spec.terraformVariables` and environment variables `spec.environmentVariables`. + + + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Workspace +metadata: + name: migration + spec: + terraformVariables: + - name: username + value: "user" + hcl: true + sensitive: false + environmentVariables: + - name: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false +``` + + + +### Module controller + +HCP Terraform Operator for Kubernetes v2 configures modules in a new `Module` controller separate from the `Workspace` controller. Below is a template of a custom resource manifest: + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Module +metadata: + name: +spec: + organization: + token: + secretKeyRef: + name: + key: + name: operator +``` + +The table below describes the mapping between the `Workspace` controller from v1 and the `Module` controller in v2 of the operator. + +| Version 1 (Workspace CRD) | Version 2 (Module CRD) | Notes | +| ---------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `spec.module` | N/A | In v2 of the operator a `Module` is a separate controller with its own CRD. | +| N/A | `spec.name: operator` | In v1 of the operator, the name of the generated module is hardcoded to `operator`. In v2, the default name of the generated module is `this`, but you can rename it. | +| `spec.module.source` | `spec.module.source` | This supports all Terraform [module sources](/terraform/language/modules/sources). | +| `spec.module.version` | `spec.module.version` | Refer to [module sources](/terraform/language/modules/sources) for versioning information for each module source. | +| `spec.variables.[*]` | `spec.variables.[*].name` | You should include variable names in the module. This is a reference to variables in the workspace that is executing the module. | +| `spec.outputs.[*].key` | `spec.outputs.[*].name` | You should include output names in the module. This is a reference to the output variables produced by the module. | +| `status.workspaceID` OR `metadata.namespace-metadata.name` | `spec.workspace.id` OR `spec.workspace.name` | The workspace where the module is executed. The workspace must be in the same organization. | + +Below is an example migration of a `Module` between v1 and v2 of the operator: + + + +```yaml +apiVersion: app.terraform.io/v1alpha1 +kind: Workspace +metadata: + name: migration +spec: + module: + source: app.terraform.io/org-name/module-name/provider + version: 0.0.42 + variables: + - key: username + value: "user" + hcl: true + sensitive: false + environmentVariable: false + - key: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false + environmentVariable: true +``` + + + +In v2 of the operator, separate controllers manage workspace and modules. + + + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Workspace +metadata: + name: migration + spec: + terraformVariables: + - name: username + value: "user" + hcl: true + sensitive: false + environmentVariables: + - name: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false +``` + + + + + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Module +metadata: + name: migration +spec: + name: operator + module: + source: app.terraform.io/org-name/module-name/provider + version: 0.0.42 + workspace: + name: migration +``` + + + +## Upgrade the operator + +Download Workspace CRD patch A: + +```shell-session +$ curl -sO https://raw.githubusercontent.com/hashicorp/hcp-terraform-operator/main/docs/migration/crds/workspaces_patch_a.yaml +``` + +View the changes that patch A applies to the workspace CRD. + +```shell-session +$ kubectl diff --filename workspaces_patch_a.yaml +``` + +Patch the workspace CRD with patch A. This patch adds `app.terraform.io/v1alpha2` support, but excludes `.status.runStatus` because it has a different format in `app.terraform.io/v1alpha1` and causes JSON un-marshalling issues. + +!> **Upgrade warning**: Once you apply a patch, Kubernetes converts existing `app.terraform.io/v1alpha1` custom resources to `app.terraform.io/v1alpha2` according to the updated schema, meaning that v1 of the operator can no longer serve custom resources. Before patching, update your existing custom resources to satisfy the v2 schema requirements. [Learn more](#manifest-schema-migration). + +```shell-session +$ kubectl patch crd workspaces.app.terraform.io --patch-file workspaces_patch_a.yaml +``` + +Install the Operator v2 Helm chart with the `helm install` command. Be sure to set the `operator.watchedNamespaces` value to the list of namespaces your Workspace resources are deployed to. If this value is not provided, the operator will watch all namespaces in the Kubernetes cluster. + +```shell-session +$ helm install \ + ${RELEASE_NAME} hashicorp/hcp-terraform-operator \ + --version 2.4.0 \ + --namespace ${RELEASE_NAMESPACE} \ + --set 'operator.watchedNamespaces={white,blue,red}' \ + --set controllers.agentPool.workers=5 \ + --set controllers.module.workers=5 \ + --set controllers.workspace.workers=5 +``` + +Next, create a Kubernetes secret to store the HCP Terraform API token following the [Usage Guide](https://github.com/hashicorp/hcp-terraform-operator/blob/main/docs/usage.md#prerequisites). The API token can be copied from the Kubernetes secret that you created for v1 of the operator. By default, this is named `terraformrc`. Use the `kubectl get secret` command to get the API token. + +```shell-session +$ kubectl --namespace ${RELEASE_NAMESPACE} get secret terraformrc -o json | jq '.data.credentials' | tr -d '"' | base64 -d +``` + +Update existing custom resources [according to the schema migration guidance](#manifest-schema-migration) and apply your changes. + +```shell-session +$ kubectl apply --filename +``` + +Download Workspace CRD patch B. + +```shell-session +$ curl -sO https://raw.githubusercontent.com/hashicorp/hcp-terraform-operator/main/docs/migration/crds/workspaces_patch_b.yaml +``` + +View the changes that patch B applies to the workspace CRD. + +```shell-session +$ kubectl diff --filename workspaces_patch_b.yaml +``` + +Patch the workspace CRD with patch B. This patch adds `.status.runStatus` support, which was excluded in patch A. + +```shell-session +$ kubectl patch crd workspaces.app.terraform.io --patch-file workspaces_patch_b.yaml +``` + +The v2 operator will fail to proceed if a custom resource has the v1 finalizer `finalizer.workspace.app.terraform.io`. If you encounter an error, check the logs for more information. + +```shell-session +$ kubectl logs -f +``` + +Specifically, look for an error message such as the following. + + ERROR Migration {"workspace": "default/", "msg": "spec contains old finalizer finalizer.workspace.app.terraform.io"} + +The `finalizer` exists to provide greater control over the migration process. Verify the custom resource, and when you’re ready to migrate it, use the `kubectl patch` command to update the `finalizer` value. + +```shell-session +$ kubectl patch workspace migration --type=merge --patch '{"metadata": {"finalizers": ["workspace.app.terraform.io/finalizer"]}}' +``` + +Review the operator logs once more and verify there are no error messages. + +```shell-session +$ kubectl logs -f +``` + +The operator reconciles resources during the next sync period. This interval is set by the `operator.syncPeriod` configuration of the operator and defaults to five minutes. + +If you have any migrated `Module` custom resources, apply them now. + +```shell-session +$ kubectl apply --filename +``` + +In v2 of the operator, the `applyMethod` is set to `manual` by default. In this case, a new run in a managed workspace requires manual approval. Run the following command for each `Workspace` resource to change it to `auto` approval. + +```shell-session +$ kubectl patch workspace --type=merge --patch '{"spec": {"applyMethod": "auto"}}' +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/setup.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/setup.mdx new file mode 100644 index 0000000000..fa9517afbf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/kubernetes/setup.mdx @@ -0,0 +1,98 @@ +--- +page_title: Set up the Terraform Enterprise Operator for Kubernetes +description: >- + Learn how to install and configure the Terraform Enterprise Operator for + Kubernetes. +source: terraform-docs-common +--- + +# Set up the HCP Terraform Operator for Kubernetes + +The HCP Terraform Operator for Kubernetes' CustomResourceDefinitions (CRD) allow you to dynamically create HCP Terraform workspaces with Terraform modules, populate workspace variables, and provision infrastructure with Terraform runs. + +You can install the operator with the official [HashiCorp Helm chart](https://github.com/hashicorp/hcp-terraform-operator). + +## Prerequisites + +All HCP Terraform users can use the HCP Terraform Operator for Kubernetes. You can use the operator to manage the supported features that your organization's pricing tier enables. + +## Networking requirements + +The HCP Terraform Operator for Kubernetes makes outbound requests over HTTPS (TCP port 443) to the HCP Terraform application APIs. This may require perimeter networking as well as container host networking changes, depending on your environment. Refer to [HCP Terraform IP Ranges](/terraform/enterprise/architectural-details/ip-ranges) for more information about IP ranges. Below, we list the services that run on specific IP ranges. + +| Hostname | Port/Protocol | Directionality | Purpose | +| ------------------ | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | +| `app.terraform.io` | tcp/443, HTTPS | Outbound | Dynamically managing HCP Terraform workspaces and returning the output to Kubernetes with the HCP Terraform API | + +For self-managed Terraform Enterprise instances, ensure that the operator can reach your Terraform Enterprise hostname over HTTPS (TCP port 443). + +## Compatibility + +The HCP Terraform Operator for Kubernetes supports the following versions: + +- Helm 3.0.1 and above +- Kubernetes 1.15 and above + +## Install and configure + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to integrate with Kubernetes. + +2. Generate an [organization token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) within HCP Terraform or Terraform Enterprise and save it to a file. These instructions assume you are using a file named `credentials`. + +3. Set the `NAMESPACE` environment variable. This will be the namespace that you will install the Helm chart to. + + export NAMESPACE=tfc-operator-system + +4. Create the namespace. + + kubectl create namespace $NAMESPACE + +5. Create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) with the HCP Terraform API credentials. + + kubectl -n $NAMESPACE create secret generic terraformrc --from-file=credentials + +6. Add sensitive variables, such as your cloud provider credentials, to the namespace. + + kubectl -n $NAMESPACE create secret generic workspacesecrets --from-literal=secret_key=abc123 + +7. Add the HashiCorp Helm repository. + + helm repo add hashicorp https://helm.releases.hashicorp.com + +8. Install the [HCP Terraform Operator for Kubernetes with Helm](https://github.com/hashicorp/hcp-terraform-operator). By default, the operator communicates with `app.terraform.io`. When deploying in a self-managed Terraform Enterprise, you must set the `operator.tfeAddress` to the specific hostname of the Terraform Enterprise instance. + + - The following example command installs the Helm chart for HCP Terraform Cloud, which is the default: + + ```shell-session + $ helm install --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator + ``` + + - To install the Helm chart for self-managed Terraform Enterprise, specify your instance's hostname: + + ```shell-session + $ helm install --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator \ + --set operator.tfeAddress="TERRAFORM_ENTERPRISE_HOSTNAME" + ``` + + - Alternatively, you can set this configuration in the [value.yaml](https://github.com/hashicorp/hcp-terraform-operator/blob/main/charts/hcp-terraform-operator/values.yaml) file. + + ```yaml + operator: + tfeAddress: + ``` + + - Use the following command to apply the values.yaml file: + + ```shell-session + $ helm install --namespace ${NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator -f value.yaml + ``` + +9. To create a Terraform workspace, agent pool or etc, you can find different [examples](https://github.com/hashicorp/hcp-terraform-operator/tree/main/docs/examples) of the YAML manifests. + +### Upgrade + +When a new version of the HCP Terraform Operator for Kubernetes Helm Chart is available from the HashiCorp Helm repository, you can upgrade with the following command. + +```shell-session +$ helm upgrade --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/run-tasks/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/run-tasks/index.mdx new file mode 100644 index 0000000000..c64b59a21d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/run-tasks/index.mdx @@ -0,0 +1,109 @@ +--- +page_title: Set up Terraform Enterprise run task integrations +description: >- + Use run tasks to execute tasks in external systems at specific points in the + Terraform Enterprise run lifecycle. +source: terraform-docs-common +--- + +# Set up run task integrations + +In addition to using existing technology partners integrations, HashiCorp HCP Terraform customers can build their own custom run task integrations. Custom integrations have access to plan details in between the plan and apply phase, and can display custom messages within the run pipeline as well as prevent a run from continuing to the apply phase. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +## Prerequisites + +To build a custom integration, you must have a server capable of receiving requests from HCP Terraform and responding with a status update to a supplied callback URL. When creating a run task, you supply an endpoint url to receive the hook. We send a test POST to the supplied URL, and it must respond with a 200 for the run task to be created. + +This feature relies heavily on the proper parsing of [plan JSON output](/terraform/internals/json-format). When sending this output to an external system, be certain that system can properly interpret the information provided. + +## Available Run Tasks + +You can view the most up-to-date list of run tasks in the [Terraform Registry](https://registry.terraform.io/browse/run-tasks). + +## Integration Details + +When a run reaches the appropriate phase and a run task is triggered, the supplied URL will receive details about the run in a payload similar to the one below. The server receiving the run task should respond `200 OK`, or Terraform will retry to trigger the run task. + +Refer to the [Run Task Integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) for the exact payload specification. + +```json +{ + "payload_version": 1, + "stage": "post_plan", + "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q", + "capabilities": { + "outcomes": true + }, + "configuration_version_download_url": "https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download", + "configuration_version_id": "cv-ntv3HbhJqvFzamy7", + "is_speculative": false, + "organization_name": "hashicorp", + "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output", + "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ", + "run_created_at": "2021-09-02T14:47:13.036Z", + "run_created_by": "username", + "run_id": "run-i3Df5to9ELvibKpQ", + "run_message": "Triggered via UI", + "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback", + "task_result_enforcement_level": "mandatory", + "task_result_id": "taskrs-2nH5dncYoXaMVQmJ", + "vcs_branch": "main", + "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22", + "vcs_pull_request_url": null, + "vcs_repo_url": "https://github.com/hashicorp/terraform-random", + "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace", + "workspace_id": "ws-ck4G5bb1Yei5szRh", + "workspace_name": "tfr_github_0", + "workspace_working_directory": "/terraform" +} +``` + +Once your server receives this payload, HCP Terraform expects you to callback to the supplied `task_result_callback_url` using the `access_token` as an [Authentication Header](/terraform/enterprise/api-docs#authentication) with a [jsonapi](/terraform/enterprise/api-docs#json-api-formatting) payload of the form: + +```json +{ + "data": { + "type": "task-results", + "attributes": { + "status": "running", + "message": "Hello task", + "url": "https://example.com", + "outcomes": [...] + } + } +} +``` + +HCP Terraform expects this callback within 10 minutes, or the task will be considered to have `errored`. The supplied message attribute will be displayed in HCP Terraform on the run details page. The status can be `running`, `passed` or `failed`. + +Here's what the data flow looks like: + +![Screenshot: a diagram of the user and data flow for an HCP Terraform run task](/img/docs/terraform-cloud-run-tasks-diagram.png) + +Refer to the [run task integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration#structured-results) for the exact payload specifications, and the [run task JSON schema](https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-result.json) for code generation and payload validation. + +## Securing your Run Task + +When creating your run task, you can supply an HMAC key which HCP Terraform will use to create a signature of the payload in the `X-Tfc-Task-Signature` header when calling your service. + +The signature is a sha512 sum of the webhook body using the provided HMAC key. The generation of the signature depends on your implementation, however an example of how to generate a signature in bash is provided below. + +```bash +$ echo -n $WEBHOOK_BODY | openssl dgst -sha512 -hmac "$HMAC_KEY" +``` + +## HCP Packer Run Task + +> **Hands On:** Try the [Set Up HCP Terraform Run Task for HCP Packer](/packer/tutorials/hcp/setup-hcp-terraform-run-task), [Standard tier run task image validation](/packer/tutorials/hcp/run-tasks-data-source-image-validation), and [Plus tier run task image validation](/packer/tutorials/hcp/run-tasks-resource-image-validation) tutorials to set up and test the HCP Terraform Run Task integration end to end. + +[Packer](https://www.packer.io/) lets you create identical machine images for multiple platforms from a single source template. The [HCP Packer registry](/hcp/docs/packer) lets you track golden images, designate images for test and production environments, and query images to use in Packer and Terraform configurations. + +The HCP Packer validation run task checks the image artifacts within a Terraform configuration. If the configuration references images marked as unusable (revoked), the run task fails and provides an error message containing the number of revoked artifacts and whether HCP Packer has metadata for newer versions. For HCP Packer Plus registries, run tasks also help you identify hardcoded and untracked images that may not meet security and compliance requirements. + +To get started, [create an HCP Packer account](https://cloud.hashicorp.com/products/packer) and follow the instructions in the [HCP Packer Run Task](/hcp/docs/packer/manage-image-use/terraform-cloud-run-tasks) documentation. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/admin-guide.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/admin-guide.mdx new file mode 100644 index 0000000000..735371a432 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/admin-guide.mdx @@ -0,0 +1,56 @@ +--- +page_title: Configure the ServiceNow Service Catalog integration +description: Learn how to configure the ServiceNow Service Catalog integration workers. +source: terraform-docs-common +--- + +# Configure the ServiceNow Service Catalog integration + +ServiceNow administrators have several options with configuring the Terraform +integration. + +If you haven't yet installed the integration, see the [installation +documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform). + +Once the integration has been installed, you can add and customize a service +catalog and VCS repositories using the [service catalog +documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config). + +You can also configure how frequently ServiceNow will poll HCP Terraform using +the documentation below. + +## Configure Polling Workers + +The integration includes 3 ServiceNow Scheduled Flows to poll the HCP Terraform +API using ServiceNow Outbound HTTP REST requests. By default, all flows +schedules are set to 5 minutes. These can be customized inside the ServiceNow +Server Studio: + +1. Select the Worker Poll Run State Flow. +2. Adjust Repeat Intervals +3. Click "Done" +4. Click "Save" +5. Click "Activate" + +### Worker Poll Apply Run + +This worker approves runs for any workspaces that have finished a Terraform plan +and are ready to apply their changes. It also adds a comment on the request item +for those workspaces notifying that a run has been triggered. + +### Worker Poll Destroy Workspace + +This worker looks for any records in the Terraform ServiceNow table that are +marked for deletion with the value `is_destroyable` set to true. It then checks +the status of the workspace to ensure it is ready to be deleted. Once the +destroy run has been completed, this work will send the delete request for the +workspace to Terraform. + +### Worker Poll Run State + +The worker synchronizes ServiceNow with the current run state of Terraform +workspaces by polling the HCP Terraform API. On state changes, the worker adds +a comment to the ServiceNow request item with the updated run state and other +metadata. + +![screenshot: ServiceNow integration comments](/img/docs/service-now-comments.png) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/developer-reference.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/developer-reference.mdx new file mode 100644 index 0000000000..13ae4b2163 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/developer-reference.mdx @@ -0,0 +1,112 @@ +--- +page_title: ServiceNow Service Catalog integration developer reference +description: Learn how developers can customize the ServiceNow Service Catalog integration. +source: terraform-docs-common +--- + +# Terraform ServiceNow Service Catalog Integration Developer Reference + +The Terraform ServiceNow integration can be customized by ServiceNow developers +using the information found in this document. + +## Terraform Variables and ServiceNow Variable Sets + +ServiceNow has the concept of a Variable Set which is a collection of ServiceNow +Variables that can be referenced in a Flow from a Service Catalog item. The +Terraform Integration codebase can create [Terraform Variables and Terraform +Environment Variables](/terraform/enterprise/workspaces/variables) via the API using the +`tf_variable.createVariablesFromSet()` function. + +This function looks for variables following these conventions: + +| ServiceNow Variable Name | HCP Terraform Variable | +| -------------------------------- | ---------------------------------------------------------- | +| `tf_var_VARIABLE_NAME` | Terraform Variable: `VARIABLE_NAME` | +| `tf_env_ENV_NAME` | Environment Variable: `ENV_NAME` | +| `sensitive_tf_var_VARIABLE_NAME` | Sensitive Terraform Variable (Write Only): `VARIABLE_NAME` | +| `sensitive_tf_env_ENV_NAME` | Sensitive Environment Variable (Write Only): `ENV_NAME` | + +This function takes the ServiceNow Variable Set and HCP Terraform workspace +ID. It will loop through the given variable set collection and create any +necessary Terraform variables or environment variables in the workspace. + +## Customizing with ServiceNow "Script Includes" Libraries + +The Terraform/ServiceNow Integration codebase includes [ServiceNow Script +Includes +Classes](https://docs.servicenow.com/csh?topicname=c_ScriptIncludes.html&version=latest) +that are used to interface with HCP Terraform. The codebase also includes +example catalog items and flows that implement the interface to the HCP Terraform API. + +These classes and examples can be used to help create ServiceNow Catalog Items +customized to your specific ServiceNow instance and requirements. + +### Script Include Classes + +The ServiceNow Script Include Classes can be found in the ServiceNow Studio > +Server Development > Script Include. + +| Class Name | Description | +| ---------------------- | -------------------------------------------------------------- | +| `tf_config` | Helper to pull values from the SN Terraform Configs Table | +| `tf_get_workspace` | Client-callable script to retrieve workspace data | +| `tf_http` | ServiceNow HTTP REST wrapper for requests to the Terraform API | +| `tf_no_code_workspace` | Resources for Terraform no-code module API requests | +| `tf_run` | Resources for Terraform run API requests | +| `tf_terraform_record` | Manage ServiceNow Terraform Table Records | +| `tf_test_config` | Client-callable script to test Terraform connectivity | +| `tf_util` | Miscellaneous helper functions | +| `tf_variable` | Resources for Terraform variable API Requests | +| `tf_vcs_record` | Manage ServiceNow Terraform VCS repositories table records | +| `tf_workspace` | Resources for Terraform workspace API requests | + +### Example Service Catalog Flows and Actions + +The ServiceNow Service Catalog for Terraform provides sample catalog items that use **Flows** +and **Workflows** as their primary process engines. **Flows** are a newer solution developed +by ServiceNow and are generally preferred over **Workflows**. To see which engine an item is using, open it +in the edit mode and navigate to the **Process Engine** tab. For example, **Create Workspace** uses a **Workflow**, +whereas **Create Workspace Flow** is built upon a **Flow**. You can access both in the **Studio**. You can also +manage **Flows** in the **Flow Designer**. To manage **Workflows**, navigate to **All > Workflow Editor**. + +You can find the ServiceNow Example Flows for Terraform in the **ServiceNow Studio > Flows** (or **All > Flow Designer**). +Search for items that belong to the **Terraform** application. By default, Flows execute when someone submits an order request +for a catalog item based on a Flow. Admins can customize the Flows and Actions to add approval flows, set approval rules based +on certain conditions, and configure multiple users or roles as approvers for specific catalog items. + +| Flow Name | Description | +| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Create Workspace | Creates a new HCP Terraform workspace from VCS repository. | +| Create Workspace with Vars | Creates a new HCP Terraform workspace from VCS repository and creates any variables provided. | +| Create Run | Creates and queues a new run in the HCP Terraform workspace. | +| Apply Run | Applies a run in the HCP Terraform workspace. | +| Provision Resources | Creates a new HCP Terraform workspace (with auto-apply), creates and queues a run, then applies the run when ready. | +| Provision Resources with Vars | Creates a new HCP Terraform workspace (with auto-apply), creates any variables, creates/queues a run, applies the run when ready. | +| Provision No-Code Workspace and Deploy Resources | Creates a new HCP Terraform workspace based on a no-code module configured in the private registry (with auto-apply), creates any variables, creates and queues a run, then applies the run when ready. | +| Delete Workspace | Creates a destroy run plan. | +| Worker Poll Run State | Polls the HCP Terraform API for the current run state of a workspace. | +| Worker Poll Apply Run | Polls the HCP Terraform API and applies any pending Terraform runs. | +| Worker Poll Destroy Workspace | Queries ServiceNow Terraform Records for resources marked `is_destroyable`, applies the destroy run to destroy resources, and deletes the corresponding Terraform workspace. | +| Update No-Code Workspace and Deploy Resources | Updates an existing no-code workspace to the most recent no-code module version, updates that workspace's attached variable values, and then starts a new Terraform run. | +| Update Workspace | Updates HCP Terraform workspace configurations, such as VCS repository, description, project, execution mode, and agent pool ID (if applicable). | +| Update Workspace with Vars | Allows you to change details about the HCP Terraform workspace configurations and attached variable values. | +| Update Resources | Updates HCP Terraform workspace details and starts a new Terraform run with these new values. | +| Update Resources with Vars | Updates your existing HCP Terraform workspace and its variables, then starts a Terraform run with these updated values. | + +## ServiceNow ACLs + +Access control lists (ACLs) restrict user access to objects and operations based +on permissions granted. This integration includes the following roles that can +be used to manage various components. + +| Access Control Roles | Description | +| :---------------------------------- | --------------------------------------------------------------------------------------------- | +| `x_terraform.config_user` | Can manage the connection from the ServiceNow application to your HCP Terraform organization. | +| `x_terraform.terraform_user` | Can manage all of the Terraform resources created in ServiceNow. | +| `x_terraform.vcs_repositories_user` | Can manage the VCS repositories available for catalog items to be ordered by end-users. | + +For users who only need to order from the Terraform Catalog, we recommend +creating another role with read-only permissions for +`x_terraform_vcs_repositories` to view the available repositories for ordering +infrastructure. Install the Terraform ServiceNow Service Catalog integration by +following [the installation guide](/terraform/enterprise/integrations/service-now/service-catalog-terraform). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/example-customizations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/example-customizations.mdx new file mode 100644 index 0000000000..c14d11a220 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/example-customizations.mdx @@ -0,0 +1,174 @@ +--- +page_title: ServiceNow Service Catalog integration example configurations +description: >- + Learn from example common customizations of the ServiceNow Service Catalog + integration. +source: terraform-docs-common +--- + +# ServiceNow Service Catalog integration example configurations + +This example use case creates a Terraform Catalog Item for requesting resources +with custom variable values passed to the Terraform configuration. + +## Change the scope + +When you make a customization to the app, ensure you switch to the "Terraform" +scope. This guarantees that all items you create are correctly assigned to that +scope. To change the scope in your ServiceNow instance, click the globe icon at +the top right of the screen. For detailed instructions on changing the scope, +refer to the [ServiceNow +documentation](https://developer.servicenow.com/dev.do#!/learn/learning-plans/xanadu/new_to_servicenow/app_store_learnv2_buildneedit_xanadu_application_scope). + +## Make a copy of the existing Catalog Item + +The ServiceNow Service Catalog for Terraform application provides pre-configured [Catalog +Items](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference#example-service-catalog-flows-and-actions) +for immediate use. We recommend creating a copy of the most recent version of the +Catalog Item to ensure you have access to the latest features and +improvements. Make a copy of the most appropriate Catalog Item for your specific +business requirements by following these steps: + +1. Navigate to **All > Service Catalog > Catalogs > Terraform Catalog**, and review the + Catalog Items based on flows, whose names use the suffix "Flow". + We recommend choosing Flows over Workflows because Flows provide enhanced functionality and performance and are actively developed by ServiceNow. + For more information, refer + to [Catalog Items based on Flows vs. Workflows](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference#example-service-catalog-flows-and-actions). +2. Open the Catalog Item in editing mode: + 1. Click the Catalog Item to open the request form. + 2. Click **...** in the top right corner. + 3. Select **Configure Item** from the menu. + ![Screenshot: ServiceNow Configure Catalog Item](/img/docs/servicenow-catalog-configure-item.png "Screenshot of the ServiceNow Configure Catalog Item dropdown menu") +3. Click the **Process Engine** tab in the Catalog Item configuration. Take + note of the Flow name associated with the Catalog Item, because you need to + create a copy of this Flow as well. + ![Screenshot: ServiceNow Process Engine](/img/docs/servicenow-catalog-process-engine.png "Screenshot of the ServiceNow Configure Catalog Item – Process Engine tab") +4. Start the copying process: + 1. Click the **Copy** button above the **Related Links** section. + 2. Assign a new name to the copied Catalog Item. + 3. Optionally, modify the description and short description fields. + Right-click the header and select **Save**. + ![Screenshot: ServiceNow Copy Item](/img/docs/servicenow-catalog-copied-item.png "Screenshot of the copied ServiceNow Catalog Item") + +## Adjust the Variable Set + +If a Catalog Item requires users to input variable values, +you must update the variable set with those required variables. +Although some default Catalog Items come with pre-defined example variables, it +is common practice to remove these and replace them with your own custom +variables. + +1. Create a new Variable Set. + 1. On the Catalog Item's configuration page, under the **Related Links** + section, click the **Variable Sets** tab. + 2. Click the **New** button to create a new variable set. Ensure that the + variables in your new set match the variables required by your Terraform + configuration. + ![Screenshot: ServiceNow New Variable Set](/img/docs/servicenow-catalog-new-varset.png "Screenshot of the ServiceNow Catalog Item – new Variable Set") + 3. Select **Single-Row Variable Set** and provide a title and description. + 4. Click **Submit**. Upon submission, you will be redirected back to the Catalog + Item's configuration page. + ![Screenshot: ServiceNow New Variable Set Form](/img/docs/servicenow-catalog-new-varset-form.png "Screenshot of the ServiceNow Catalog Item – new Variable Set") + 5. Click the name of your newly created Variable Set and create your + variables. You must follow the [naming convention for Terraform + variables](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference#terraform-variables-and-servicenow-variable-sets). + ServiceNow offers various types of variable representation (such as strings, + booleans, and dropdown menus). Refer to the [ServiceNow documentation on + variables](https://docs.servicenow.com/csh?topicname=c_ServiceCatalogVariables.html&version=latest) + and select the types that best suit your use case. You can also set default + values for the variables in the **Default Value** tab, which ServiceNow prefills for the end users. + ![Screenshot: ServiceNow New Variables](/img/docs/servicenow-catalog-variables.png "Screenshot of the ServiceNow Catalog Item – new variables") +2. Attach the newly created Variable Set to your custom Catalog Item and remove + the default Workspace Variables. + 1. Return to the **Variable Sets** tab on the Catalog Item's configuration page + and click the **Edit** button. + 2. Move the "Workspace Variables" Set from the right side to the left side + and click **Save**. Do not remove the + "Workspace Request Create" or the "Workspace Request Update" Sets. + ![Screenshot: ServiceNow Remove Example Variables](/img/docs/servicenow-catalog-remove-example-variables.png "Screenshot of the ServiceNow Catalog Item – new variables") + +## Make a copy of the Flow and Action + +1. Open the ServiceNow Studio by navigating to **All > Studio** and open the + "Terraform" application. Once in the **Terraform** application, navigate to + **Flow Designer > Flows**. + ![Screenshot: ServiceNow Flow Designer Interface](/img/docs/servicenow-catalog-original-flow.png "Screenshot of the ServiceNow Flow Designer – selecting a Flow") + + Another way to access the ServiceNow Studio is to click **All**, select + "Flow Designer", then select **Flows**. You can set the **Application** + filter to "Terraform" to quickly find the desired Flow. +2. Open the Flow referenced in your Catalog Item. Click **...** + in the top right corner of the Flow Designer interface and + select **Copy flow**. Provide a name for the copied Flow and + click **Copy**. + ![Screenshot: ServiceNow Copy Flow Interface](/img/docs/servicenow-catalog-copy-flow.png "Screenshot of the ServiceNow Flow Designer – copying a Flow") +3. Customize your newly copied Flow by clicking **Edit flow**. + ![Screenshot: ServiceNow Edit New Flow Interface](/img/docs/servicenow-catalog-edit-flow.png "Screenshot of the ServiceNow Flow Designer – editing a Flow") + 1. Do not change the **Service Catalog** trigger. + 2. Update the "Get Catalog Variables" action: + 1. Keep the "Requested Item Record" in the **Submitted Request** field. + 2. Select your newly created Catalog Item from the dropdown menu for + **Template Catalog Item**. + 3. Move all of your variables to the **Selected** side in the **Catalog + Variables** section. Remove any previous example variables from the + **Available** side. + ![Screenshot: ServiceNow Get Variables Flow Step](/img/docs/servicenow-catalog-get-variables.png "Screenshot of the ServiceNow Flow Designer – getting Variables step") + 4. Click **Done** to finish configuring this Action. +4. Unfold the second Action in the Flow and click the arrow to open it in + the Action Designer. + ![Screenshot: ServiceNow Open Action Designer](/img/docs/servicenow-catalog-open-action.png "Screenshot of the ServiceNow Action Designer") + 1. Click **...** in the top right corner and select **Copy Action**. + ![Screenshot: ServiceNow Copy Action](/img/docs/servicenow-catalog-copy-action.png "Screenshot of the ServiceNow Copy Action") + Rename it and click **Copy**. + ![Screenshot: ServiceNow Rename Action](/img/docs/servicenow-catalog-rename-action.png "Screenshot of the ServiceNow Rename Action") + 2. In the the Inputs section, remove any previous example variables. + ![Screenshot: ServiceNow Remove Variables From Action](/img/docs/servicenow-catalog-remove-example-variables-from-action.png "Screenshot of the ServiceNow Action Input Variables") + 3. Add your custom variables by clicking the **Create Input** button. Ensure that the variable names match your Catalog Item variables and select the variable type that matches each variable. Click **Save**. + ![Screenshot: ServiceNow Add Variables To Action](/img/docs/servicenow-catalog-add-variables-to-action.png "Screenshot of adding ServiceNow Action Input Variables") + 4. Open the **Script step** within the Action. Remove any example variables + and add your custom variables by clicking **Create Variable** at the + bottom. Enter the name of each variable and drag the corresponding data + pill from the right into the **Value field**. + ![Screenshot: ServiceNow Add Script Step Variables To Action](/img/docs/servicenow-catalog-adjust-script-variables.png "Screenshot of adjusting ServiceNow Action Script Variables") + 5. Click **Save** and then **Publish**. +5. Reopen the Flow and attach the newly created Action to the Flow + after "Get Catalog Variables" step: + 1. Remove the "Create Terraform Workspace with Vars" Action that you copied earlier and replace it with + your newly created Action. + ![Screenshot: ServiceNow Replace Action Step](/img/docs/servicenow-catalog-replace-action.png "Screenshot of replacing ServiceNow Action step") + 2. Connect the new Action to the Flow by dragging and dropping the data pills + from the "Get Catalog Variables" Action to the corresponding inputs of + your new Action. Click **Done** to save this step. + ![Screenshot: ServiceNow Fill Variables for Action](/img/docs/servicenow-catalog-fill-new-action-step.png "Screenshot of filling out ServiceNow Action variables") + 3. Click **Save**. + 4. Click **Activate** to enable the Flow and make it available for use. + +## Set the Flow for your Catalog Item + +1. Navigate back to the Catalog by clicking on **All** and then go to **Service + Catalog > Catalogs > Terraform Catalog**. +2. Locate your custom Catalog Item and click **...** at the top + of the item. From the dropdown menu, select **Configure item**. +3. In the configuration settings, click the **Process Engine** tab. +4. In the **Flow** field, search for the Flow you recently created. Click + the Flow then click the **Update**. + ![Screenshot: ServiceNow Update Process Engine](/img/docs/servicenow-catalog-update-process-engine.png "Screenshot of updating Process Engine for the Catalog Item") + +## Test the Catalog Item + +The new item is now available in the Terraform Service Catalog. To make the +new item accessible to your end users via the Service Portal, follow these +steps: + +1. Navigate to the configuration page of the item you want to make available. +2. Locate the **Catalogs** field on the configuration page and click the lock + icon next to it. +3. In the search bar, type "Service Catalog" and select it from the search + results. Add "Service Catalog" to the list of catalogs associated with the + item. Click the lock icon again to lock the changes. + ![Screenshot: ServiceNow Enable Service Portal](/img/docs/servicenow-catalog-service-portal.png "Screenshot of adding the Catalog Item to the Service Portal") +4. Click the **Update** button at the top of the page. + +After completing these steps, end users will be able to +access the new item through the Service Portal of your ServiceNow instance. You +can access the Service Portal by navigating to **All > Service Portal Home**. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/index.mdx new file mode 100644 index 0000000000..83f0111836 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/index.mdx @@ -0,0 +1,239 @@ +--- +page_title: Set up ServiceNow Service Catalog integration for Terraform Enterprise +description: >- + Learn how to set up the ServiceNow Service Catalog integration for Terraform + Enterprise. +source: terraform-docs-common +--- + +# Set up ServiceNow Service Catalog integration for HCP Terraform + +-> **Integration version:** v2.8.1 + +The Terraform ServiceNow Service Catalog integration enables your end-users to +provision self-serve infrastructure via ServiceNow. By connecting ServiceNow to +HCP Terraform, this integration lets ServiceNow users order Service Items, +create workspaces, and perform Terraform runs using prepared Terraform +configurations hosted in VCS repositories or as [no-code +modules](/terraform/enterprise/no-code-provisioning/module-design) for +self-service provisioning. + + + +@include 'tfc-package-callouts/servicenow-catalog.mdx' + + + +## Summary of the Setup Process + +The integration relies on Terraform ServiceNow Catalog integration software +installed within your ServiceNow instance. Installing and configuring this +integration requires administration in both ServiceNow and HCP Terraform. +Since administrators of these services within your organization are not +necessarily the same person, this documentation refers to a **ServiceNow Admin** +and a **Terraform Admin**. + +First, the Terraform Admin configures your HCP Terraform organization with a +dedicated team for the ServiceNow integration, and obtains a team API token for +that team. The Terraform Admin provides the following to your ServiceNow admin: + +- An Organization name +- A team API token +- The hostname of your HCP Terraform instance +- Any available no-code modules or version control repositories containing Terraform configurations +- Other required variables + token, the hostname of your HCP Terraform instance, and details about no-code + modules or version control repositories containing Terraform configurations and + required variables to the ServiceNow Admin. + +Next, the ServiceNow Admin will install the Terraform ServiceNow Catalog +integration to your ServiceNow instance, and configure it using the team API +token and hostname. + +Finally, the ServiceNow Admin will create a Service Catalog within ServiceNow +for the Terraform integration, and configure it using the version control +repositories or no-code modules, and variable definitions provided by the +Terraform Admin. + +| ServiceNow Admin | Terraform Admin | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | Prepare an organization for use with the ServiceNow Catalog. | +| | Create a team that can manage workspaces in that organization. | +| | Create a team API token so the integration can use that team's permissions. | +| | If using VCS repositories, retrieve the OAuth token IDs and repository identifiers that HCP Terraform uses to identify your VCS repositories. If using a no-code flow, [create a no-code ready module](/terraform/enterprise/no-code-provisioning/provisioning) in your organization's private registry. Learn more in [Configure VCS Repositories or No-Code Modules](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#configure-vcs-repositories-or-no-code-modules). | +| | Provide the API token, OAuth token ID, repository identifiers, variable definitions, and HCP Terraform hostname to the ServiceNow Admin. | +| Install the Terraform integration application from the ServiceNow App Store. | | +| Connect the integration application with HCP Terraform. | | +| Add the Terraform Service Catalog to ServiceNow. | | +| If you are using the VCS flow, configure the VCS repositories in ServiceNow. | | +| Configure variable sets for use with the VCS repositories or no-code modules. | | + +Once these steps are complete, self-serve infrastructure will be available +through the ServiceNow Catalog. HCP Terraform will provision and manage +requested infrastructure and report the status back to ServiceNow. + +## Prerequisites + +To start using Terraform with the ServiceNow Catalog Integration, you must have: + +- An administrator account on a Terraform Enterprise instance or within a + HCP Terraform organization. +- An administrator account on your ServiceNow instance. +- If you are using the VCS flow, one or more [supported version control + systems](/terraform/enterprise/vcs#supported-vcs-providers) (VCSs) with read + access to repositories with Terraform configurations. +- If you are using no-code provisioning, one or more [no-code modules](/terraform/enterprise/no-code-provisioning/provisioning) created in + your organization's private registry. Refer to the [no-code module + configuration](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#no-code-module-configuration) + for information about using no-code modules with the ServiceNow Service Catalog + for Terraform. + +You can use this integration on the following ServiceNow server versions: + +- Washington DC +- Xanadu +- Yokohama + +It requires the following ServiceNow plugins as dependencies: + +- Flow Designer support for the Service Catalog (`com.glideapp.servicecatalog.flow_designer`) +- ServiceNow IntegrationHub Action Step - Script (`com.glide.hub.action_step.script`) +- ServiceNow IntegrationHub Action Step - REST (`com.glide.hub.action_step.rest`) + +-> **Note:** Dependent plugins are installed on your ServiceNow instance automatically when the app is downloaded from the ServiceNow Store. + +## Configure HCP Terraform + +Before installing the ServiceNow integration, the Terraform Admin will need to +perform the following steps to configure and gather information from HCP +Terraform. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Either [create an + organization](/terraform/enterprise/users-teams-organizations/organizations#creating-organizations) + or choose an existing organization where ServiceNow will create new + workspaces. + **Save the organization name for later.** +3. [Create a team](/terraform/enterprise/users-teams-organizations/teams) for that + organization called "ServiceNow", and ensure that it has [permission to + manage + workspaces](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces). + You do not need to add any users to this team. + [permissions-citation]: #intentionally-unused---keep-for-maintainers +4. On the "ServiceNow" team's settings page, generate a [team API + token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + **Save the team API token for later.** +5. If you are using the [VCS flow](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#vcs-configuration): + 1. Ensure your Terraform organization is [connected to a VCS provider](/terraform/enterprise/vcs). Repositories that are connectable to HCP Terraform workspaces can also be used as workspace templates in the ServiceNow integration. + 2. On your organization's VCS provider settings page (**Settings** > **VCS Providers**), find the OAuth Token ID for the VCS provider(s) that you intend to use with the ServiceNow integration. HCP Terraform uses the OAuth token ID to identify and authorize the VCS provider. **Save the OAuth token ID for later.** + 3. Identify the VCS repositories in the VCS provider containing Terraform configurations that the ServiceNow Terraform integration will deploy. Take note of any Terraform or environment variables used by the repositories you select. Save the Terraform and environment variables for later. +6. If using the [no-code flow](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#no-code-module-configuration), create one or more no-code modules in the private registry of your HCP Terraform. **Save the no-code module names for later.** +7. Provide the following information to the ServiceNow Admin: + - The organization name + - The team API token + - The hostname of your Terraform Enterprise instance, or of HCP Terraform. The hostname of HCP Terraform is `app.terraform.io`. + - The no-code module name(s) or the OAuth token ID(s) of your VCS provider(s), and the repository identifier for each VCS repository containing Terraform configurations that will be used by the integration. + - Any Terraform or environment variables required by the configurations in the + given VCS repositories. + +-> **Note:** Repository identifiers are determined by your VCS provider; they +typically use a format like `/` or +`/`. Azure DevOps repositories use the format +`//_git/`. A GitHub repository hosted at +`https://github.com/exampleorg/examplerepo/` would have the repository +identifier `exampleorg/examplerepo`. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +For instance, if you are configuring this integration for your company, `Example +Corp`, using two GitHub repositories, you would share values like the following +with the ServiceNow Admin. + +```markdown +Terraform Enterprise Organization Name: `ServiceNowExampleOrg` + +Team API Token: `q2uPExampleELkQ.atlasv1.A7jGHmvufExampleTeamAPITokenimVYxwunJk0xD8ObVol054` + +Terraform Enterprise Hostname: `terraform.corp.example` + +OAuth Token ID (GitHub org: example-corp): `ot-DhjEXAMPLELVtFA` + - Repository ID (Developer Environment): `example-corp/developer-repo` + - Environment variables: + - `AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY` + - `AWS_SECRET_ACCESS_KEY=ZB0ExampleSecretAccessKeyGjUiJh` + - `AWS_DEFAULT_REGION=us-west-2` + - Terraform variables: + - `instance_type=t2.medium` + - Repository ID (Testing Environment): `example-corp/testing-repo` + - Environment variables: + - `AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY` + - `AWS_SECRET_ACCESS_KEY=ZB0ExampleSecretAccessKeyGjUiJh` + - `AWS_DEFAULT_REGION=us-west-2` + - Terraform variables: + - `instance_type=t2.large` +``` + +## Install the ServiceNow Integration + +Before beginning setup, the ServiceNow Admin must install the Terraform +ServiceNow Catalog integration software. + +This can be added to your ServiceNow instance from the [ServiceNow +Store](https://store.servicenow.com/sn_appstore_store.do). Search for the "Terraform" integration, +published by "HashiCorp Inc". + +![Screenshot: ServiceNow Store Page](/img/docs/service-now-store.png "Screenshot of the ServiceNow Store listing for the Terraform Integration") + +## Connect ServiceNow to HCP Terraform + +-> **ServiceNow Roles:** `admin` or `x_terraform.config_user` + +Once the integration is installed, the ServiceNow Admin can connect your +ServiceNow instance to HCP Terraform. Before you begin, you will need the +information described in the "Configure HCP Terraform" section from your +Terraform Admin. + +Once you have this information, connect ServiceNow to HCP Terraform with +the following steps. + +1. Navigate to your ServiceNow Service Management Screen. +2. Using the left-hand navigation, open the configuration table for the + integration to manage the HCP Terraform connection. + - Terraform > Configs +3. Click on "New" to create a new HCP Terraform connection. + - Set Org Name to the HCP Terraform organization name. + - Click on the "Lock" icon to set Hostname to the hostname of your Terraform + Enterprise instance. If you are using the SaaS version of HCP Terraform, + the hostname is `https://app.terraform.io`. Be sure to include "https://" + before the hostname. + - Set API Team Token to the HCP Terraform team API token. + - (Optional) To use the [MID Server](https://docs.servicenow.com/csh?topicname=mid-server-landing.html&version=latest), + select the checkbox and type the `name` in the `MID Server Name` field. +4. Click "Submit". + +![Screenshot: ServiceNow Terraform Config](/img/docs/service-now-updated-config.png "Screenshot of the ServiceNow Terraform Config New Record page") + +## Create and Populate a Service Catalog + +Now that you have connected ServiceNow to HCP Terraform, you are ready to +create a Service Catalog using the VCS repositories or no-code modules provided +by the Terraform Admin. + +Navigate to the [Service Catalog documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config) to +begin. You can also refer to this documentation whenever you need to add or +update request items. + +### ServiceNow Developer Reference + +ServiceNow developers who wish to customize the Terraform integration can refer +to the [developer documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference). + +### ServiceNow Administrator's Guide. + +Refer to the [ServiceNow Administrator documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/admin-guide) for +information about configuring the integration. + +### Example Customizations + +Once the ServiceNow integration is installed, you can consult the [example +customizations documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/example-customizations). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config.mdx new file mode 100644 index 0000000000..ce972ed701 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config.mdx @@ -0,0 +1,255 @@ +--- +page_title: Create and manage ServiceNow Service Catalog items with Terraform Enterprise +description: >- + Create and manage service catalog items to allow end users to provision + infrastructure using ServiceNow and Terraform Enterprise. +source: terraform-docs-common +--- + +# Create and manage ServiceNow Service Catalog items + +When using ServiceNow with the HCP Terraform integration, you will configure +at least one service catalog item. You will also configure one or more version +control system (VCS) repositories or no-code modules containing the Terraform +configurations which will be used to provision that infrastructure. End users +will request infrastructure from the service catalog, and HCP Terraform will +fulfill the request by creating a new workspace, applying the configuration, and +then reporting the results back to ServiceNow. + +## Prerequisites + +Before configuring a service catalog, you must install and configure the +HCP Terraform integration software on your ServiceNow instance. These steps +are covered in the [installation documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform). + +Additionally, you must have have the following information: + +1. The no-code module name or the OAuth token ID and repository identifier for + each VCS repository that HCP Terraform will use to provision + infrastructure. Your Terraform Admin will provide these to you. Learn more in + [Configure VCS Repositories or No-Code + Modules](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#configure-vcs-repositories-or-no-code-modules). +2. Any Terraform or environment variables required by the configurations in the + given VCS repositories or no-code modules. + +Once these steps are complete, in order for end users to provision +infrastructure with ServiceNow and HCP Terraform, the ServiceNow Admin will +perform the following steps to make Service Items available to your end users. + +1. Add at least one service catalog for use with Terraform. +2. If you are using the VCS flow, configure at least one one VCS repository in ServiceNow. +3. Create variable sets to define Terraform and environment variables to be used + by HCP Terraform to provision infrastructure. + +## Add the Terraform Service Catalog + +-> **ServiceNow Role:** `admin` + +First, add a Service Catalog for use with the Terraform integration. Depending +on your organization's needs, you might use a single service catalog, or +several. If you already have a Service Catalog to use with Terraform, skip to +the next step. + +1. In ServiceNow, open the Service Catalog > Catalogs view by searching for + "Service Catalog" in the left-hand navigation. + 1. Click the plus sign in the top right. + 2. Select "Catalogs > Terraform Catalog > Title and Image" and choose a + location to add the Service Catalog. + 3. Close the "Sections" dialog box by clicking the "x" in the upper right-hand + corner. + +-> **Note:** In step 1, be sure to choose "Catalogs", not "Catalog" from the +left-hand navigation. + +## Configure VCS Repositories or No-Code Modules + +-> **ServiceNow Roles:** `admin` or `x_terraform.vcs_repositories_user` + +Terraform workspaces created through the ServiceNow Service Catalog for +Terraform can be associated with a VCS +provider repository or be backed by a [no-code +module](/terraform/enterprise/no-code-provisioning/provisioning) in your +organization's private registry. Administrators determine which workspace type +end users can request from the Terraform Catalog. Below are the key +differences between the version control and no-code approaches. + +### VCS configuration + +To make infrastructure available to your users through version control +workspaces, you must add one or more VCS repositories containing Terraform +configurations to the Service Catalog for Terraform. + +1. In ServiceNow, open the "Terraform > VCS Repositories" table by searching for + "Terraform" in the left-hand navigation. +2. Click "New" to add a VCS repository, and fill in the following fields: + - Name: The name for this repository. This name will be visible to end + users, and does not have to be the same as the repository name as defined + by your VCS provider. Ideally it will succinctly describe the + infrastructure that will be provisioned by Terraform from the repository. + - OAuth Token ID: The OAuth token ID that from your HCP Terraform + organization's VCS providers settings. This ID specifies which VCS + provider configured in HCP Terraform hosts the desired repository. + - Identifier: The VCS repository that contains the Terraform configuration + for this workspace template. Repository identifiers are determined by your + VCS provider; they typically use a format like + `/` or `/`. Azure DevOps + repositories use the format `//_git/`. + - The remaining fields are optional. + - Branch: The branch within the repository, if different from the default + branch. + - Working Directory: The directory within the repository containing + Terraform configuration. + - Terraform Version: The version of Terraform to use. This will default to + the latest version of Terraform supported by your HCP Terraform + instance. +3. Click "Submit". + +![Screenshot: ServiceNow New VCS Repository](/img/docs/service-now-vcs-repository.png "Screenshot of the ServiceNow Terraform New VCS Repository page") + +After configuring your repositories in ServiceNow, the names of those +repositories will be available in the "VCS Repository" dropdown menu a user +orders new workspaces through the following items in the Terraform Catalog: + +- **Create Workspace** +- **Create Workspace with Variables** +- **Provision Resources** +- **Provision Resources with Variables** + +### No-Code Module Configuration + +In version 2.5.0 and newer, ServiceNow administrators can configure +Catalog Items using [no-code +modules](/terraform/enterprise/no-code-provisioning/provisioning). This release +introduces two new additions to the Terraform Catalog - no-code workspace +create and update Items. Both utilize no-code modules from the private registry +in HCP Terraform to enable end users to request infrastructure without writing +code. + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +The following Catalog Items allow you to build and manage workspaces with +no-code modules: + +- **Provision No-Code Workspace and Deploy Resources**: creates a new Terraform + workspace based on a no-code module of your choice, supplies required variable + values, runs and applies Terraform. +- **Update No-Code Workspace and Deploy Resources**: Updates an existing no-code + workspace to the most recent no-code module version, updates that workspace's + attached variable values, and then starts and applies a new Terraform run. + +Administrators can skip configuring VCS repositories in ServiceNow when using +no-code modules. The only input required in the no-code workspace request form +is the name of the no-code module. + +Before utilizing a no-code module, you must publish it to the your organization's +private module registry. With this one-time configuration complete, ServiceNow +Administrators can then call the modules through Catalog requests without +repository management, simplifying the use of infrastructure-as-code. + +> **Hands On:** Try the [Self-service enablement with HCP Terraform and ServiceNow tutorial](/terraform/tutorials/it-saas/servicenow-no-code). + +## Configure a Variable Set + +Most Terraform configurations can be customized with Terraform variables or +environment variables. You can create a Variable Set within ServiceNow to +contain the variables needed for a given configuration. Your Terraform Admin +should provide these to you. + +1. In ServiceNow, open the "Service Catalog > Variable Sets" table by searching for + "variable sets" in the left-hand navigation. +2. Click "New" to add a Variable Set. +3. Select "Single-Row Variable Set". + - Title: User-visible title for the variable set. + - Internal name: The internal name for the variable set. + - Order: The order in which the variable set will be displayed. + - Type: Should be set to "Single Row" + - Application: Should be set to "Terraform" + - Display title: Whether the title is displayed to the end user. + - Layout: How the variables in the set will be displayed on the screen. + - Description: A long description of the variable set. +4. Click "Submit" to create the variable set. +5. Find and click on the title of the new variable set in the Variable Sets + table. +6. At the bottom of the variable set details page, click "New" to add a new + variable. + +- Type: Should be "Single Line Text" for most variables, or "Masked" for + variables containing sensitive values. +- Question: The user-visible question or label for the variable. +- Name: The internal name of the variable. This must be derived from the name of the + Terraform or environment variable. Consult the table below to determine the + proper prefix for each variable name. +- Tooltip: A tooltip to display for the variable. +- Example Text: Example text to show in the variable's input box. + +1. Under the "Default Value" tab, you can set a default value for the variable. +2. Continue to add new variables corresponding to the Terraform and environment + variables the configuration requires. + +When the Terraform integration applies configuration, it will map ServiceNow +variables to Terraform and environment variables using the following convention. +ServiceNow variables that begin with "sensitive\_" will be saved as sensitive +variables within HCP Terraform. + +| ServiceNow Variable Name | HCP Terraform Variable | +| -------------------------------- | ---------------------------------------------------------- | +| `tf_var_VARIABLE_NAME` | Terraform Variable: `VARIABLE_NAME` | +| `tf_env_ENV_NAME` | Environment Variable: `ENV_NAME` | +| `sensitive_tf_var_VARIABLE_NAME` | Sensitive Terraform Variable (Write Only): `VARIABLE_NAME` | +| `sensitive_tf_env_ENV_NAME` | Sensitive Environment Variable (Write Only): `ENV_NAME` | + +## Provision Infrastructure + +Once you configure the Service Catalog for Terraform, ServiceNow users +can request infrastructure to be provisioned by HCP Terraform. + +These requests will be fulfilled by HCP Terraform, which will: + +1. Create a new workspace from the no-code module or the VCS repository provided by ServiceNow. +2. Configure variables for that workspace, also provided by ServiceNow. +3. Plan and apply the change. +4. Report the results, including any outputs from Terraform, to ServiceNow. + +Once this is complete, ServiceNow will reflect that the Request Item has been +provisioned. + +-> **Note:** The integration creates workspaces with +[auto-apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) +enabled. HCP Terraform will queue an apply for these workspaces whenever +changes are merged to the associated VCS repositories. This is known as the +[VCS-driven run workflow](/terraform/enterprise/run/ui). It is important to keep in mind +that all of the ServiceNow workspaces connected to a given repository will be +updated whenever changes are merged to the associated branch in that repository. + +## Execution Mode + +If using v2.2.0 or above, the Service Catalog app allows you to set an [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) for your Terraform workspaces. There are two modes to choose from: + +- The default value is "Remote", which instructs HCP Terraform to perform runs on its disposable virtual machines. +- Selecting "Agent" mode allows you to run Terraform operations on isolated, private, or on-premises infrastructure. This option requires you to create an Agent Pool in your organization beforehand, then provide that Agent Pool's id when you order a new workspace through the Service Catalog. + + + +@include 'tfc-package-callouts/agents.mdx' + + + +## Workspace Name + +Version 2.4.0 of the Service Catalog for Terraform introduces the ability to set custom names for your Terraform workspaces. You can choose a prefix for your workspace name that the Service Catalog app will append the ServiceNow RITM number to. If you do not define a workspace prefix, ServiceNow will use RITM number as the workspace name. + +Workspace names can include letters, numbers, dashes (`-`), and underscores (`_`), and should not exceed 90 characters. +Refer to the [workspace naming recommendations](/terraform/enterprise/workspaces/create#workspace-naming) for best practices. + +## Workspace Tags + +Version 2.8.0 extends support for the key-value pair tags while still also supporting flat string tags version 2.4.0 introduced. Use the "Workspace Tags" field to provide a comma-separated list of key-value pair tags in the format "env: prod, instance: test" that will be parsed and attached to the workspace in HCP Terraform. + +Tags give you an easier way to categorize, filter, and manage workspaces provisioned through the Service Catalog for Terraform. +We recommend that you set naming conventions for tags with your end users to avoid variations such as `ec2`, `aws-ec2`, `aws_ec2`. + +Workspace tags have a 255 character limit and can contain letters, numbers, colons, hyphens, and underscores. Refer to the [workspace tagging rules](/terraform/enterprise/workspaces/create#workspace-tags) for more details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/troubleshoot.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/troubleshoot.mdx new file mode 100644 index 0000000000..b43864651c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-catalog-terraform/troubleshoot.mdx @@ -0,0 +1,120 @@ +--- +page_title: >- + Troubleshoot the ServiceNow Service Catalog Integration for Terraform + Enterprise +description: Troubleshooting tips for ServiceNow Service Catalog Integration. +source: terraform-docs-common +--- + +# Troubleshoot the ServiceNow Service Catalog integration + +This page offers troubleshooting tips for common issues with the ServiceNow Service Catalog Integration for HCP Terraform. +It also provides instructions on how to find and read logs to diagnose and resolve issues. + +## Find logs + +Logs are crucial for diagnosing issues. You can find logs in ServiceNow in the following places: + +### Workflow logs + +To find workflow logs, click on the RITM number on a failed ticket to open the request item. +Scroll down to **Related Links > Workflow Context** and open the **Workflow Log** tab. + +### Flow logs + +To find flow logs, click on the RITM number on a failed ticket to open the request item. +Scroll down to **Related Links > Flow Context > Open Context Record** and open the **Flow engine log entries** tab. + +### Application logs + +To find application logs, navigate to **All > System Log > Application Logs.** +Set the **Application** filter to "Terraform". +Search for logs around the time your issue occurred. Some records include HTTP status codes and detailed error messages. + +### Outbound requests + +ServiceNow logs all outgoing API calls, including calls to HCP Terraform. To view the log of outbound requests, navigate to **All > System Logs > Outbound HTTP Requests.** +To customize the table view, add columns like "URL," "URL Path," and "Application scope." +Logs from the Catalog app are marked with the `x_325709_terraform` scope. + +## Enable email notifications + +To enable email notifications and receive updates on your requested item tickets: + +1. Log in to your ServiceNow instance as an administrator. +2. **Click System Properties > Email Properties**. +3. In the **Outbound Email Configuration** panel, select **Yes** next to the check-box with the email that ServiceNow should send notifications to. + +To ensure you have relevant notifications configured in your instance: + +1. Navigate to **System Notification > Email > Notifications.** +2. Search for "Request Opened" and "Request Item Commented" and ensure they are activated. + +Reach out to ServiceNow customer support if you run into any issues with the global configurations. + +## Common problems + +This section details frequently encountered issues and how they can be resolved. + +### Failure to create a workspace + +If you order the "create a workspace" catalog item and nothing happens in ServiceNow and HCP Terraform does not create a workspace then there are several possible reasons why: + +Ensure your HCP Terraform token, hostname, and organization name is correct. + +1. Make sure to use a **Team API Token**. This can be found in HCP Terraform under "API Tokens". +2. Ensure the team API token has the correct permissions. +3. Double-check your organization name by copying and pasting it from HCP Terraform or Terraform Enterprise. +4. Double-check your host name. +5. Make sure you created your team API token in the same organization you are using +6. Test your configuration. First click **Update** to process any changes then \*\*Test Config to make sure the connection is working. + +Verify your VCS configuration. + +1. The **Identifier** field should not have any spaces. The ServiceNow Service Catalog Integration requires that you format repository names in the `username/repo_name` format. +2. The **Name** can be anything, but it is better to avoid special characters as per naming convention. +3. Double-check the OAuth token ID in your HCP Terraform/Terraform Enterprise settings. To retrieve your OAuth token ID, navigate to your HCP Terraform organization's settings page, then click **Provider** in the left navigation bar under **Version Control**. + +### Failure to successfully order any catalog item + +After placing an order for any catalog item, navigate to the comments section in the newly created RITM ticket. +The latest comment will contain a response from HCP Terraform. + +### Frequency of comments and outputs + +When you place an order in the Terraform Catalog, ServiceNow submits and processes the order, then attaches additional comments to the order to indicate whether HCP Terraform successfully created the workspace. + +By default, ServiceNow polls HCP Terraform every 5 minutes for the latest status of the Terraform run. ServiceNow does not show any comments until the next ping. + +To configure ServiceNow to poll HCP Terraform more frequently: + +1. Navigate to **All > Flow designer**. +2. Set the **Application** filter to **Terraform**. +3. Under the **Name** column click **Worker Poll Run State**. +4. Click on the trigger and adjust the interval to your desired schedule. +5. Click **Done > Save > Activate** to save your changes. + +### Using no-code modules feature + +If ServiceNow fails to deploy a no-code module catalog item, verify the following: + +1. Ensure that your HCP Terraform organization has an [HCP Plus tier](https://www.hashicorp.com/products/terraform/pricing) subscription. +2. Ensure the name you enter for your no-code module in the catalog user form matches the no-code module in HCP Terraform. + +### Updating no-code workspaces + +If the “update no-code workspace” catalog item returns the output message “No update has been made to the workspace”, then you have not upgraded your no-code module in HCP Terraform. + +### Application Scope + +If you are making customizations and you encounter unexpected issues, make sure to change the scope from **Global** to **Terraform** and recreate your customized items in the **Terraform scope**. +For additional instructions on customizations, refer to the [example customizations](/terraform/enterprise/integrations/service-now/service-catalog-terraform/example-customizations) documentation. + +### MID server + +If you are using a MID server in your configuration, check the connectivity by using the **Test Config** button on the configurations page. +Additionally, when ServiceNow provisions a MID server, navigate to **MID Servers > Servers** to check if the status is “up” and “validated”. + +### Configuration + +While the app allows multiple config entries, only one should be present as this can interfere with the functionality of the app. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/customizations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/customizations.mdx new file mode 100644 index 0000000000..9263ecc2a0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/customizations.mdx @@ -0,0 +1,97 @@ +--- +page_title: Customize the ServiceNow Service Graph Connector for Terraform Enterprise +description: >- + Learn how to edit ETL mappings in the ServiceNow Service Graph Connector for + Terraform Enterprise integration. +source: terraform-docs-common +--- + +# Customize the ServiceNow Service Graph Connector for Terraform + +-> **ServiceNow roles:** `admin` + +-> **ServiceNow plugin requirement:** `IntegrationHub ETL` + +You can update and customize the default ETL mapping rules offered by the Service Graph Connector for Terraform. + +To ensure that your custom rules remain intact during future updates, you can clone the existing ETL record and maintain it separately from the default one. + +This documentation guides you through the process of mapping a resource using an example of an AWS virtual private network (VPC). Although this resource is already covered by the application, the principles discussed apply to any new potential resource mapping. + +Any customizations should be done from the application's scope: **Service Graph Connector for Terraform**. + +## Clone the ETL map + +Navigate to the **IntegrationHub ETL** in the top menu. Check the **SG-Terraform** record and click **Duplicate**. Refer to the [ServiceNow documentation](https://docs.servicenow.com/en-US/bundle/utah-servicenow-platform/page/product/configuration-management/task/duplicate-cmdb-transform-map.html) to create a duplicate of an existing ETL transform map. + +## Build a resource in HCP Terraform + +Create a new workspace in your HCP Terraform organization and create a Terraform resource that you would like to map. It helps to have a Terraform state record of the resource to ensure accurate mapping. + +[Configure a webhook](/terraform/enterprise/integrations/service-now/service-graph/service-graph-setup#configure-terraform-webhook) and initiate a Terraform run. + +## Download Terraform State + +Once the run is successfully completed, open your ServiceNow instance, click on **All** and navigate to **Scheduled Imports**. + +Open the **SG-Terraform Scheduled Process State** record, search for the import set corresponding to the latest webhook request. Click the **Import Set** field to open the import set. Wait for the import set to be successfully processed. + +Since there are no existing ETL rules configured for the new resource, it is ignored during the ETL process. + +Open the **Outbound Http Requests** tab to list the requests sent from your ServiceNow instance to HCP Terraform and get the latest state of the workspace. + +![ServiceNow Service Graph Connector Outbound Http Requests interface](/img/docs/service-now-service-graph-state-object-url.png) + +Open the record that starts with " by clicking on the timestamp. Copy the content of the URL field and open it you your browser to download the Terraform state file. + +Locate the resource in the state object. This JSON record will serve as a source for the future mapping. + +## Identify the CI target + +Pick a suitable Configuration Item (CI) target for your resource. For example, the AWS virtual private network (VPC) resource is mapped to Cloud Network (`cmdb_ci_network`) by the Service Graph Connector for Terraform. Refer to the [ServiceNow CMDB documentation](https://docs.servicenow.com/en-US/bundle/utah-servicenow-platform/page/product/configuration-management/reference/cmdb-tables-details.html) for more details on available CI tables. + +## Consult the CI Class Manager + +After selecting an appropriate CI target, it is important to consult the CI Class Manager for guidance on dependent relationships. Many CMDB resources rely on other CI tables. If a related class is not properly mapped, the ETL job will generate errors or warnings and fail to import your resource into the CMDB. + +In the top navigation, click on **All**, search for **CI Class Manager**, and click on **Open Hierarchy**. Search for your target CI Class and check **Dependent Relationships** tab to learn more about dependent mappings required by the resource. + +For example, according to the **CI Class Manager**, **Cloud Network** should be hosted on **Logical Datacenter** and **Cloud Service Account**. + +## Set the mapping rules + +Open the **IntegrationHub ETL** from the top navigation menu and select your cloned ETL map record prepared for customization. Refer to the [ServiceNow documentation](https://docs.servicenow.com/en-US/bundle/utah-servicenow-platform/page/product/configuration-management/concept/create-etl-transform-map.html) for instructions to create an ETL transform map. + +Click on the first **Specify Basic Details** section of the ETL Transform Map Assistant. Select the import set number containing your resource from the **Sample Import Set** dropdown and click **Mark as Complete**. + +Open the **Preview and Prepare Data** section and review the imported rows. Click **Mark as Complete**. + +The third section provides the interface for mapping resource attributes. Click on **Select CMDB Classes to Map Source Data**. Click on **Add Conditional Class** button at the top. Set the rules that will identify your resource in the import set. Use the `type` field value from the Terraform state object to identify your resource (on the ServiceNow side, field name are prefaced with `u_`). Set the target CMDB CI Class name and click **Save**. + +![ServiceNow Service Graph Connector: setting the Conditional Class rules in the ETL mapping](/img/docs/service-now-service-graph-conditional-class-mapping.png) + +To modify the mapping for your new Conditional Class record, select **Edit Mapping**. On the right side of the interface, drag the relevant data pills and drop them into the corresponding CMDB fields on the left side. Refer to the Terraform state record to verify the presence of attributes. For uniqueness, the **Source Native Key** value is typically mapped to the `arn` field when dealing with AWS resources. All resources mapped in the Service Graph Connector for Terraform will have the **Operational status** and **Name** fields populated. + +![ServiceNow Service Graph Connector: mapping resource attributes in the ETL](/img/docs/service-now-service-graph-etl-attribute-mapping.png) + +Once the mapping is completed, click on the left arrow at the top to return to the list of Conditional Classes. Map two more conditional classes in the same manner, according to the rules set in the CI Class Manager: **Logical Datacenter** (**AWS Datacenter** in case of AWS VPC) and **Cloud Service Account**. Since the AWS cloud provider is already covered by the application, these classes are already present. Click **Edit Class** to include your newly mapped resource into the listed conditional rules. Add another **OR** condition to each of them and click **Save**. + +![ServiceNow Service Graph Connector: updating conditions on existing parent records when a new resource is mapped](/img/docs/service-now-service-graph-etl-condition-update.png) + +Click **Mark as Complete** to finalize the **Select CMDB Classes to Map Source Data** section. + +## Set the required relationships + +Click **Add Relationships** to continue to the next section. Click the **Add Conditional Relationship** button at the top of the page. The following configuration tells the ETL that when a record with `aws_vpc` type is found in the import set, it should be hosted on **AWS Datacenter 1**. Click **Save**. + +![ServiceNow Service Graph Connector: setting dependent relationships in the ETL mapping interface](/img/docs/service-now-service-graph-etl-setting-relationship.png) + +A similar dependent relationship needs to be established from **AWS Datacenter** to **Cloud Service Account**. Since the AWS cloud provider is already covered by the application, the relationship record is present in the application. Click **Edit Relationship** and add another **OR** condition containing your new resource to the list. Click **Save**. + +![ServiceNow Service Graph Connector: updating existing dependent relationships in the ETL mapping interface](/img/docs/service-now-service-graph-etl-editing-relationship.png) + +Click **Mark as Complete** to finalize the **Add Relationships** section. + +## Run a test + +There are two ways to test the new resource mapping. You can utilize the **Test and Rollback Integration Results** interface of the ETL Transform Map Assistant. Alternatively, you can initiate a new run in your HCP Terraform workspace that includes the deployment of the resource. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/index.mdx new file mode 100644 index 0000000000..e625181e1e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/index.mdx @@ -0,0 +1,83 @@ +--- +page_title: ServiceNow Service Graph Connector for Terraform Enterprise overview +description: >- + Use the ServiceNow Service Graph Connector to enable users to import Terraform + Enterprise-built infrastructure into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector for Terraform overview + +-> **Integration version:** v1.2.0 + +Use the Service Graph Connector for Terraform to securely import HCP Terraform resources into your ServiceNow instance. The ServiceNow Service Graph for Terraform is a certified scoped application available in the [ServiceNow Store](https://store.servicenow.com/sn_appstore_store.do#!/store/application/0b0600891b52c150c216ebd56e4bcb32). + +The integration is based on the [Service Graph Connector](https://www.servicenow.com/products/service-graph-connectors.html) technology that provides a framework for discovering and mapping relationships between the organization's infrastructure and the ServiceNow Configuration Items (CIs), and then automatically updating the [ServiceNow CMDB (Configuration Management Database)](https://www.servicenow.com/products/servicenow-platform/configuration-management-database.html) with this information. This enables platform teams to gain a comprehensive view of the resources they support. The CMDB is a central repository within the ServiceNow platform, which provides a single source of truth for your infrastructure and offers configurable dashboards for monitoring and reporting. + +## Key benefits + +- **Enhanced visibility**: The Service Graph Connector for Terraform updates the CMDB dashboards with resources deployed in HCP Terraform. +- **Improved efficiency**: By connecting Terraform to the ServiceNow CMDB, platform teams can manage and search Terraform-provisioned resources in the CMDB alongside the rest of the company's infrastructure. +- **Consistent management**: Terraform state file changes get automatically and securely updated in the ServiceNow CMDB, capturing status changes for all technical resources in a timely manner. +- **Extensibility**: ServiceNow admins can customize mappings for additional resource types, potentially working with HashiCorp’s entire Terraform ecosystem made up of thousands of providers. + +## Technical design + +The diagram below shows how the Service Graph Connector for Terraform connects HCP Terraform to your ServiceNow instance. + +![ServiceNow Service Graph Connector for Terraform: design diagram](/img/docs/service-now-service-graph-design.png) + +The Service Graph Connector for Terraform integrates with HCP Terraform to fetch up-to-date information about your deployments. It leverages the Terraform state as the primary data source. The application doesn't make any requests to your cloud provider or require you to share any cloud credentials. + +## Import methods + +The integration offers two methods of importing your Terraform resources into CMDB. You can configure the application to periodically pull all your resources in one batch. Alternatively, you can set up webhooks in your Terraform workspaces, which will notify your ServiceNow instance about new deployments. + +### Scheduled polling + +The Service Graph Connector for Terraform can be scheduled to periodically poll HCP Terraform. Depending on the size of your infrastructure and how frequently the state of your resources needs to be refreshed in CMDB, the polling schedule can be set anywhere from once a week to every second. This option is not recommended for big environments with thousands of Terraform workspaces as the import job will take several hours to complete. + +The scheduled job makes a request to HCP Terraform to obtain all organizations that the HCP Terraform API token provided to the application has access to. It will attempt to import all relevant resources from all workspaces within each of those organizations. The processing time depends of the number of organizations and workspaces in HCP Terraform. Configuring the import job to run frequently is not recommended for big environments. + +To access the scheduler, search for **Service Graph Connector for Terraform** in the top navigation menu and select **SG-Import Schedule**. You can change the polling settings and view all previous import sets pulled into your ServiceNow instance using this method. + +### HCP Terraform Webhook Notifications + +You can configure [webhook notifications](/terraform/enterprise/workspaces/settings/notifications) for all relevant workspaces in HCP Terraform organization. Webhooks offer an event-based approach to importing your resources. The import is triggered as soon as a Terraform run is successfully completed in HCP Terraform. + +Webhook POST requests are sent to an API endpoint exposed by the Service Graph Connector for Terraform in your ServiceNow instance. Each webhook request includes an HMAC token, and the endpoint validates the signature using the secret you provide. Learn more about [HCP Terraform notification authenticity](/terraform/enterprise/workspaces/settings/notifications#notification-authenticity). + +Internally, the application uses a scheduled job as a helper to keep track of the incoming webhook requests. To activate, configure, and view the history of all webhook imports, navigate to **Scheduled Imports** and select **SG-Terraform Scheduled Process State**. By default, the job is set to run every minute. + +-> **Tip:** Both import options may be enabled, or you may choose to configure only the webhooks or the scheduled import. + +The [setup page](/terraform/enterprise/integrations/service-now/service-graph/service-graph-setup) provides configuration details for both import modes. + +## ETL (Extract, Transform, Load) + +After the application successfully imports the resources, they are temporarily stored in a staging database table. The import set records are then transferred to the ETL (Extract, Transform, Load) pipeline. Search for **IntegrationHub ETL** in the top navigation menu to view and edit the default ETL rules of the Service Graph Connector for Terraform. The application's ETL Transform Map is called **SG-Terraform**. + +To deactivate resources that you do not want imported into the CMDB, navigate to the **Select CMDB Classes to Map Source Data** section of the application's ETL record, and toggle the switch on the resource mapping record to deactivate it. + +![screenshot: ServiceNow Service Graph Connector for Terraform resource ETL deactivation button](/img/docs/service-now-service-graph-deactivate-etl.png) + +-> **Tip:** Run an import before you open the ETL map as the interface requires at least one import set stored in the memory to be able to display the rules. + +## Supported resources + +The Service Graph Connector for Terraform supports selected resources from the following cloud providers: + +- AWS +- Microsoft Azure +- Google Cloud +- VMware vSphere + +The [resource mapping](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage) documentation contains tables detailing the mapping of objects and attributes between HCP Terraform and ServiceNow CMDB. + +## Destroyed resources + +After the destroy operation is completed in HCP Terraform and the application's import job is finished in your ServiceNow instance, the **Operational Status** field of all resources in the CMDB removed from the Terraform state during the deletion process will be updated to **Non-Operational**. + +## Get started + +Refer to the [setup page](/terraform/enterprise/integrations/service-now/service-graph/service-graph-setup) for information on how to configure the integration in your ServiceNow instance. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/aws.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/aws.mdx new file mode 100644 index 0000000000..d2ccc40b18 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/aws.mdx @@ -0,0 +1,219 @@ +--- +page_title: ServiceNow Service Graph Connector AWS resource coverage +description: >- + Use the ServiceNow Service Graph integration to import selected resources from + AWS into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector AWS resource coverage + +This page details the mapping rules for importing AWS resources, provisioned with Terraform, into ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| AWS resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ------------------------------------------------------------------------------------- | --------------------------- | -------------------------------- | ----------------------------- | +| AWS account | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| AWS region | N/A | `cmdb_ci_aws_datacenter` | AWS Datacenter | +| EC2 Instance | `aws_instance` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| S3 Bucket | `aws_s3_bucket` | `cmdb_ci_cloud_object_storage` | Cloud Object Storage | +| ECS Cluster | `aws_ecs_cluster` | `cmdb_ci_cloud_ecs_cluster` | AWS Cloud ECS Cluster | +| EKS Cluster | `aws_eks_cluster` | `cmdb_ci_kubernetes_cluster` | Kubernetes Cluster | +| VPC | `aws_vpc` | `cmdb_ci_network` | Cloud Network | +| Database Instance (_non-Aurora databases: e.g., MySQL, PostgreSQL, SQL Server, etc._) | `aws_db_instance` | `cmdb_ci_cloud_database` | Cloud DataBase | +| RDS Aurora Cluster | `aws_rds_cluster` | `cmdb_ci_cloud_db_cluster` | Cloud DataBase Cluster | +| RDS Aurora Instance | `aws_rds_cluster_instance` | `cmdb_ci_cloud_database` | Cloud DataBase | +| DynamoDB Global Table | `aws_dynamodb_global_table` | `cmdb_ci_dynamodb_global_table` | DynamoDB Global Table | +| DynamoDB Table | `aws_dynamodb_table` | `cmdb_ci_dynamodb_table` | DynamoDB Table | +| Security Group | `aws_security_group` | `cmdb_ci_compute_security_group` | Compute Security Group | +| Lambda | `aws_lambda_function` | `cmdb_ci_cloud_function` | Cloud Function | +| Load Balancer | `aws_lb` | `cmdb_ci_cloud_load_balancer` | Cloud Load Balancer | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ----------------------------------------------------------- | ----------------- | --------------------------------------------------------- | +| AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | Hosted On::Hosts | Cloud Service Account 1 (`cmdb_ci_cloud_service_account`) | +| AWS Datacenter 2 (`cmdb_ci_aws_datacenter`) | Hosted On::Hosts | Cloud Service Account 6 (`cmdb_ci_cloud_service_account`) | +| Virtual Machine Instance 1 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Virtual Machine Instance 1 (`cmdb_ci_vm_instance`) | Reference | Key Value 1 (`cmdb_key_value`) | +| AWS Cloud ECS Cluster 1 (`cmdb_ci_cloud_ecs_cluster`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| AWS Cloud ECS Cluster 1 (`cmdb_ci_cloud_ecs_cluster`) | Reference | Key Value 2 (`cmdb_key_value`) | +| Cloud Object Storage 1 (`cmdb_ci_cloud_object_storage`) | Hosted On::Hosts | AWS Datacenter 2 (`cmdb_ci_aws_datacenter`) | +| Cloud Object Storage 1 (`cmdb_ci_cloud_object_storage`) | Reference | Key Value 3 (`cmdb_key_value`) | +| Kubernetes Cluster 1 (`cmdb_ci_kubernetes_cluster`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Kubernetes Cluster 1 (`cmdb_ci_kubernetes_cluster`) | Reference | Key Value 4 (`cmdb_key_value`) | +| Cloud Network 1 (`cmdb_ci_network`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud Network 1 (`cmdb_ci_network`) | Reference | Key Value 5 (`cmdb_key_value`) | +| Cloud DataBase 1 (`cmdb_ci_cloud_database` ) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud DataBase 1 (`cmdb_ci_cloud_database` ) | Reference | Key Value 6 (`cmdb_key_value`) | +| Cloud DataBase Cluster 1 (`cmdb_ci_cloud_db_cluster`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud DataBase Cluster 1 (`cmdb_ci_cloud_db_cluster`) | Reference | Key Value 7 (`cmdb_key_value`) | +| DynamoDB Global Table 1 (`cmdb_ci_dynamodb_global_table`) | Hosted On::Hosts | Cloud Service Account 1 (`cmdb_ci_cloud_service_account`) | +| DynamoDB Table 1 (`cmdb_ci_dynamodb_table`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| DynamoDB Table 1 (`cmdb_ci_dynamodb_table`) | Reference | Key Value 8 (`cmdb_key_value`) | +| Compute Security Group 1 (`cmdb_ci_compute_security_group`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Compute Security Group 1 (`cmdb_ci_compute_security_group`) | Reference | Key Value 10 (`cmdb_key_value`) | +| Cloud Function 1 (`cmdb_ci_cloud_function`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud Function 1 (`cmdb_ci_cloud_function`) | Reference | Key Value 11 (`cmdb_key_value`) | +| Cloud Load Balancer 1 (`cmdb_ci_cloud_load_balancer`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud Load Balancer 1 (`cmdb_ci_cloud_load_balancer`) | Reference | Key Value 12 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | -------------------------------------------- | +| Source Native Key | Resource account number extracted from `arn` | +| Account Id | Resource account number extracted from `arn` | +| Datacenter Type | Resource cloud provider extracted from `arn` | +| Object ID | Resource id extracted from `arn` | +| Name | Resource name extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### AWS Datacenter (`cmdb_ci_aws_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | --------------------------------------------------------------- | +| Source Native Key | Concatenation of region and account number extracted from `arn` | +| Object Id | Region extracted from `arn` | +| Region | Region extracted from `arn` | +| Name | Region extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### Virtual Machine Instance (`cmdb_ci_vm_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Placement Group ID | `placement_group` | +| IP Address | `public_ip` | +| Status | `instance_state` | +| VM Instance ID | `id` | +| Name | `id` | +| State | `state` | +| CPU | `cpu_core_count` | +| Operational Status | Defaults to "1" ("Operational") | + +### AWS Cloud ECS Cluster (`cmdb_ci_cloud_ecs_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Object Storage (`cmdb_ci_cloud_object_storage`) + +| CMDB field | Terraform state field | +| ------------------ | -------------------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Cloud Provider | Resource cloud provider extracted from `arn` | +| Name | `bucket` | +| Operational Status | Defaults to "1" ("Operational") | + +### Kubernetes Cluster (`cmdb_ci_kubernetes_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| IP Address | `endpoint` | +| Port | Defaults to "6443" | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Network (`cmdb_ci_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase (`cmdb_ci_cloud_database`) + +| CMDB field | Terraform state field | +| --------------------------- | -------------------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Version | `engine_version` | +| Type | `engine` | +| TCP port(s) | `port` | +| Category | `instance_class` | +| Fully qualified domain name | `endpoint` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Vendor | Resource cloud provider extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase Cluster (`cmdb_ci_cloud_db_cluster`) + +| CMDB field | Terraform state field | +| --------------------------- | -------------------------------------------- | +| Source Native Key | `arn` | +| Cluster ID | `cluster_resource_id` | +| Name | `name` | +| TCP port(s) | `port` | +| Fully qualified domain name | `endpoint` | +| Vendor | Resource cloud provider extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### DynamoDB Table (`cmdb_ci_dynamodb_table`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `arn` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### DynamoDB Global Table (`cmdb_ci_dynamodb_global_table`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Compute Security Group (`cmdb_ci_compute_security_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Function (`cmdb_ci_cloud_function`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `arn` | +| Language | `runtime` | +| Code Size | `source_code_size` | +| Location | Region extracted from `arn` | +| Name | `function_name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Load Balancer (`cmdb_ci_cloud_load_balancer`) + +| CMDB field | Terraform state field | +| -------------------------- | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Canonical Hosted Zone Name | `dns_name` | +| Canonical Hosted Zone ID | `zone_id` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/azure.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/azure.mdx new file mode 100644 index 0000000000..0a503bec63 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/azure.mdx @@ -0,0 +1,158 @@ +--- +page_title: ServiceNow Service Graph Connector Microsoft Azure resource coverage +description: >- + Use the ServiceNow Service Graph integration to import selected resources from + Microsoft Azure into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector Microsoft Azure resource coverage + +This page describes how Terraform-provisioned Azure resources are mapped to the classes within the ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| Azure resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ---------------------- | --------------------------------- | -------------------------------- | ----------------------------- | +| Azure account | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| Azure region | N/A | `cmdb_ci_azure_datacenter` | Azure Datacenter | +| Resource Group | `azurerm_resource_group` | `cmdb_ci_resource_group` | Resource Group | +| Windows VM | `azurerm_windows_virtual_machine` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| Linux VM | `azurerm_linux_virtual_machine` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| AKS Cluster | `azurerm_kubernetes_cluster` | `cmdb_ci_kubernetes_cluster` | Kubernetes Cluster | +| Storage Container | `azurerm_storage_container` | `cmdb_ci_cloud_storage_account` | Cloud Storage Account | +| MariaDB Database | `azurerm_mariadb_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| MS SQL Database | `azurerm_mssql_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| MySQL Database | `azurerm_mysql_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| PostgreSQL Database | `azurerm_postgresql_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| Network security group | `azurerm_network_security_group` | `cmdb_ci_compute_security_group` | Compute Security Group | +| Linux Function App | `azurerm_linux_function_app` | `cmdb_ci_cloud_function` | Cloud Function | +| Windows Function App | `azurerm_windows_function_app` | `cmdb_ci_cloud_function` | Cloud Function | +| Virtual Network | `azurerm_virtual_network` | `cmdb_ci_network` | Cloud Network | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ----------------------------------------------------------- | ---------------------- | --------------------------------------------------------- | +| Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | Hosted On::Hosts | Cloud Service Account 2 (`cmdb_ci_cloud_service_account`) | +| Azure Datacenter 2 (`cmdb_ci_azure_datacenter`) | Hosted On::Hosts | Cloud Service Account 3 (`cmdb_ci_cloud_service_account`) | +| Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | Contains::Contained by | Resource Group 1 (`cmdb_ci_resource_group`) | +| Cloud Storage Account 1 (`cmdb_ci_cloud_storage_account`) | Hosted On::Hosts | Azure Datacenter 2 (`cmdb_ci_azure_datacenter`) | +| Virtual Machine Instance 2 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Virtual Machine Instance 2 (`cmdb_ci_vm_instance`) | Reference | Key Value 14 (`cmdb_key_value`) | +| Virtual Machine Instance 3 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Virtual Machine Instance 3 (`cmdb_ci_vm_instance`) | Reference | Key Value 15 (`cmdb_key_value`) | +| Kubernetes Cluster 2 (`cmdb_ci_kubernetes_cluster`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Kubernetes Cluster 2 (`cmdb_ci_kubernetes_cluster`) | Reference | Key Value 16 (`cmdb_key_value`) | +| Cloud DataBase 2 (`cmdb_ci_cloud_database` ) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Cloud DataBase 2 (`cmdb_ci_cloud_database` ) | Reference | Key Value 9 (`cmdb_key_value`) | +| Compute Security Group 2 (`cmdb_ci_compute_security_group`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Compute Security Group 2 (`cmdb_ci_compute_security_group`) | Reference | Key Value 17 (`cmdb_key_value`) | +| Cloud Function 2 (`cmdb_ci_cloud_function`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Cloud Function 2 (`cmdb_ci_cloud_function`) | Reference | Key Value 19 (`cmdb_key_value`) | +| Cloud Network 2 (`cmdb_ci_network`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Cloud Network 2 (`cmdb_ci_network`) | Reference | Key Value 20 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | ----------------------------------- | +| Source Native Key | Subscription ID extracted from `id` | +| Account Id | Subscription ID extracted from `id` | +| Datacenter Type | Defaults to `azure` | +| Object ID | Subscription ID extracted from `id` | +| Name | Subscription ID extracted from `id` | +| Operational Status | Defaults to "1" ("Operational") | + +### Azure Datacenter (`cmdb_ci_azure_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | ----------------------------------------------- | +| Source Native Key | Concatenation of `location` and Subscription ID | +| Object Id | `location` | +| Region | `location` | +| Name | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Virtual Machine Instance (`cmdb_ci_vm_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Storage Account (`cmdb_ci_cloud_storage_account`) + +| CMDB field | Terraform state field | +| --------------------------- | ------------------------------- | +| Source Native Key | `resource_manager_id` | +| Object Id | `resource_manager_id` | +| Fully qualified domain name | `id` | +| Blob Service | `storage_account_name` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Resource Group (`cmdb_ci_resource_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Location | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Kubernetes Cluster (`cmdb_ci_kubernetes_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| IP Address | `fqdn` | +| Port | Defaults to "6443" | +| Name | `name` | +| Location | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase (`cmdb_ci_cloud_database`) + +| CMDB field | Terraform state field | +| --------------------------- | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Version | `engine_version` | +| Fully qualified domain name | `fqdn` | +| Name | `name` | +| Vendor | Defaults to `azure` | +| Operational Status | Defaults to "1" ("Operational") | + +### Compute Security Group (`cmdb_ci_compute_security_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Function (`cmdb_ci_cloud_function`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Network (`cmdb_ci_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/gcp.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/gcp.mdx new file mode 100644 index 0000000000..5681430c8b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/gcp.mdx @@ -0,0 +1,159 @@ +--- +page_title: ServiceNow Service Graph Connector Google Cloud resource coverage +description: >- + Use the ServiceNow Service Graph for Terraform Enterprise integration to + import selected resources from Google Cloud into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector Google Cloud resource coverage + +This page provides details on how Google Cloud resources, set up using Terraform, are corresponded to the classes within the ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| Google resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ------------------------ | --------------------------------------------------------------------- | -------------------------------- | ----------------------------- | +| Project ID | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| Region (location) | N/A | `cmdb_ci_google_datacenter` | Google Datacenter | +| Virtual Machine Instance | `google_compute_instance` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| Kubernetes Cluster | `google_container_cluster` | `cmdb_ci_kubernetes_cluster` | Kubernetes Cluster | +| Google Storage | `google_storage_bucket` | `cmdb_ci_cloud_storage_account` | Cloud Storage Account | +| Google BigQuery | `google_bigquery_table` | `cmdb_ci_cloud_database` | Cloud DataBase | +| Google SQL | `google_sql_database` | `cmdb_ci_cloud_database` | Cloud DataBase | +| Google Compute Firewall | `google_compute_firewall` | `cmdb_ci_compute_security_group` | Compute Security Group | +| Cloud Function | `google_cloudfunctions_function` or `google_cloudfunctions2_function` | `cmdb_ci_cloud_function` | Cloud Function | +| Load Balancer | `google_compute_forwarding_rule` | `cmdb_ci_cloud_load_balancer` | Cloud Load Balancer | +| VPC | `google_compute_network` | `cmdb_ci_network` | Cloud Network | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ----------------------------------------------------------- | ----------------- | --------------------------------------------------------- | +| Google Datacenter 1 (`cmdb_ci_google_datacenter`) | Hosted On::Hosts | Cloud Service Account 4 (`cmdb_ci_cloud_service_account`) | +| Google Datacenter 2 (`cmdb_ci_google_datacenter`) | Hosted On::Hosts | Cloud Service Account 4 (`cmdb_ci_cloud_service_account`) | +| Virtual Machine Instance 4 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Virtual Machine Instance 4 (`cmdb_ci_vm_instance`) | Reference | Key Value 13 (`cmdb_key_value`) | +| Cloud Network 3 (`cmdb_ci_network`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud Network 3 (`cmdb_ci_network`) | Reference | Key Value 18 (`cmdb_key_value`) | +| Compute Security Group 3 (`cmdb_ci_compute_security_group`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Compute Security Group 3 (`cmdb_ci_compute_security_group`) | Reference | Key Value 21 (`cmdb_key_value`) | +| Kubernetes Cluster 3 (`cmdb_ci_kubernetes_cluster`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Kubernetes Cluster 3 (`cmdb_ci_kubernetes_cluster`) | Reference | Key Value 22 (`cmdb_key_value`) | +| Cloud DataBase 3 (`cmdb_ci_cloud_database` ) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud DataBase 2 (`cmdb_ci_cloud_database` ) | Reference | Key Value 24 (`cmdb_key_value`) | +| Cloud Function 3 (`cmdb_ci_cloud_function`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud Function 3 (`cmdb_ci_cloud_function`) | Reference | Key Value 25 (`cmdb_key_value`) | +| Cloud Load Balancer 2 (`cmdb_ci_cloud_load_balancer`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud Load Balancer 2 (`cmdb_ci_cloud_load_balancer`) | Reference | Key Value 26 (`cmdb_key_value`) | +| Cloud Storage Account 2 (`cmdb_ci_cloud_storage_account`) | Hosted On::Hosts | Google Datacenter 2 (`cmdb_ci_google_datacenter`) | +| Cloud Storage Account 2 (`cmdb_ci_cloud_storage_account`) | Reference | Key Value 23 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `project` | +| Account Id | `project` | +| Datacenter Type | Defaults to `google` | +| Object ID | `project` | +| Name | `project` | +| Operational Status | Defaults to "1" ("Operational") | + +### Google Datacenter (`cmdb_ci_google_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | --------------------------------------------------------- | +| Source Native Key | Concatenation of `project` and region extracted from `id` | +| Object Id | Region extracted from `id` | +| Region | Region extracted from `id` | +| Name | Region extracted from `id` | +| Operational Status | Defaults to "1" ("Operational") | + +### Virtual Machine Instance (`cmdb_ci_vm_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Category | `machine_type` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Network (`cmdb_ci_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Compute Security Group (`cmdb_ci_compute_security_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Kubernetes Cluster (`cmdb_ci_kubernetes_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| IP Address | `endpoint` | +| Port | Defaults to "6443" | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Object Storage (`cmdb_ci_cloud_object_storage`) + +| CMDB field | Terraform state field | +| ------------------ | -------------------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Cloud Provider | Resource cloud provider extracted from `arn` | +| Name | `bucket` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Storage Account (`cmdb_ci_cloud_storage_account`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Name | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase (`cmdb_ci_cloud_database`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | Name extracted from `id` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Function (`cmdb_ci_cloud_function`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Load Balancer (`cmdb_ci_cloud_load_balancer`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/index.mdx new file mode 100644 index 0000000000..ec81da07cc --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/index.mdx @@ -0,0 +1,37 @@ +--- +page_title: >- + ServiceNow Service Graph Connector for Terraform Enterprise resource coverage + overview +description: >- + The ServiceNow Service Graph for Terraform Enterprise integration imports + selected resources from major cloud providers into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector for Terraform resource coverage overview + +The tables provided in this section illustrate the mapping of resources from the Terraform state to the ServiceNow CMDB configuration items (CIs) by the Service Graph Connector for Terraform. + +While the default ETL map provided by the application can be utilized without modification, it is also possible to customize it according to the specific requirements of your organization. Check [customizations](/terraform/enterprise/integrations/service-now/service-graph/customizations) for more details. + +The application supports selected resources from major cloud providers. The following pages provide mapping details for each supported provider: + +- [AWS](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/aws) +- [Azure](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/azure) +- [GCP](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/gcp) +- [VMware vSphere](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere) + +# Importing Tags + +The Service Graph Connector for Terraform imports the Terraform tags associated with your resource into CMDB. Tags are mapped to the **Key Value** CI Class. +Along with the tags assigned in your Terraform code, the integration also includes `tf_organization` and `tf_workspace` tags. These tags are used to indicate the HCP Terraform organization and workspace where the resource was provisioned. + +The visibility of the **Tags** tab in CMDB varies for different configuration items. By default, not every configuration item has the **Tags** tab enabled. For instance, the **Virtual Machine Instance** class page includes the **Tags** tab, whereas the **AWS Cloud ECS Cluster** page does not. + +The following example illustrates how the **Tags** tab can be enabled for **AWS Cloud ECS Cluster** CI class in CMDB. + +1. Enter `cmdb_ci_cloud_ecs_cluster.list` in the search menu of your ServiceNow instance. +2. Open any record. Right-click on the gray bar at the top, select **Configure** and proceed to **Related Lists**. If you are in a different scope, click **Edit this view**. +3. Transfer **Key Value->Configuration item** from the left column to the right and click **Save**. Tags become available in CMDB for all AWS ECS cluster records. + +![screenshot: ServiceNow Service Graph Connector - enable the Tags tab in CMDB](/img/docs/service-now-service-graph-tags.png) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere.mdx new file mode 100644 index 0000000000..9e9f91fe20 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere.mdx @@ -0,0 +1,84 @@ +--- +page_title: ServiceNow Service Graph Connector VMware vSphere resource coverage +description: >- + Use the ServiceNow Service Graph integration to import selected resources from + VMware vSphere into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector VMware vSphere resource coverage + +This page explains the rules of associating VMware vSphere resources, created via Terraform, with the classes in the ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| vSphere resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ------------------------- | --------------------------- | ------------------------------- | ------------------------------- | +| vCenter server | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| vSphere Datacenter | `vsphere_datacenter` | `cmdb_ci_vcenter_datacenter` | VMware vCenter Datacenter | +| vSphere Virtual Machine | `vsphere_virtual_machine` | `cmdb_ci_vmware_instance` | VMware Virtual Machine Instance | +| vSphere Datastore Cluster | `vsphere_datastore_cluster` | `cmdb_ci_vcenter_datastore` | VMware vCenter Datastore | +| vSphere Network | `vsphere_network` | `cmdb_ci_vcenter_network` | VMware vCenter Network | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ------------------------------------------------------------- | ----------------- | ---------------------------------------------------------- | +| VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | Hosted On::Hosts | Cloud Service Account 5 (`cmdb_ci_cloud_service_account`) | +| VMware Virtual Machine Instance 1 (`cmdb_ci_vmware_instance`) | Hosted On::Hosts | VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | +| VMware Virtual Machine Instance 1 (`cmdb_ci_vmware_instance`) | Reference | Key Value 27 (`cmdb_key_value`) | +| VMware vCenter Network 1 (`cmdb_ci_vcenter_network`) | Hosted On::Hosts | VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | +| VMware vCenter Network 1 (`cmdb_ci_vcenter_network`) | Reference | Key Value 28 (`cmdb_key_value`) | +| VMware vCenter Datastore 1 (`cmdb_ci_vcenter_datastore`) | Hosted On::Hosts | VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | +| VMware vCenter Datastore 1 (`cmdb_ci_vcenter_datastore`) | Reference | Key Value 29 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | Defaults to "VMware_vCenter" | +| Account Id | Defaults to "VMware_vCenter" | +| Datacenter Type | Defaults to "VMware_vCenter" | +| Object ID | Defaults to "VMware_vCenter" | +| Name | Defaults to "VMware_vCenter" | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware vCenter Datacenter (`cmdb_ci_vcenter_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `datacenter_id` | +| Object Id | `datacenter_id` | +| Region | `datacenter_id` | +| Name | `datacenter_id` | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware Virtual Machine Instance (`cmdb_ci_vmware_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware vCenter Network (`cmdb_ci_vcenter_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware vCenter Datastore (`cmdb_ci_vcenter_datastore`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/service-graph-setup.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/service-graph-setup.mdx new file mode 100644 index 0000000000..c71384b3d3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/integrations/service-now/service-graph/service-graph-setup.mdx @@ -0,0 +1,162 @@ +--- +page_title: Set up the ServiceNow Service Graph Connector for Terraform Enterprise +description: >- + Learn how to set up the ServiceNow Service Graph Connector for Terraform + Enterprise. +source: terraform-docs-common +--- + +# Set up the ServiceNow Service Graph Connector + +-> **Note:** Follow the [Configure ServiceNow Service Graph Connector for HCP Terraform](/terraform/tutorials/it-saas/servicenow-sgc) tutorial for hands-on instructions on how to import an AWS resource deployed in your HCP Terraform organization to the ServiceNow CMDB by using the Service Graph Connector for Terraform. + +The ServiceNow Service Graph Connector for Terraform is a certified scoped application available in the ServiceNow Store. Search for ”Service Graph Connector for Terraform” published by ”HashiCorp Inc” and click **Install**. + +## Prerequisites + +To start using the Service Graph Connector for Terraform, you must have: + +- An administrator account on a Terraform Enterprise instance or within an HCP Terraform organization. +- An administrator account on your ServiceNow vendor instance. + +The Service Graph Connector for Terraform supports the following ServiceNow server versions: + +- Washington DC +- Xanadu +- Yokohama + +The following ServiceNow plugins are required dependencies: + +- ITOM Discovery License +- Integration Commons for CMDB +- Discovery and Service Mapping Patterns +- ServiceNow IntegrationHub Standard Pack + +Additionally, you can install the IntegrationHub ETL application if you want to modify the default CMDB mappings. + +-> **Note:** Dependent plugins are installed on your ServiceNow instance automatically when the app is downloaded from the ServiceNow Store. Before installing the Service Graph Connector for Terraform, you must activate the ITOM Discovery License plugin in your production instance. + +## Connect ServiceNow to HCP Terraform + +-> **ServiceNow roles:** `admin`, `x_hashi_service_gr.terraform_user` + +Once the integration is installed, you can proceed to the guided setup form where you will enter your Terraform credentials. This step will establish a secure connection between HCP Terraform and your ServiceNow instance. + +### Create and scope Terraform API token + +In order for ServiceNow to connect to HCP Terraform, you must give it an HCP Terraform API token. The permissions of this token determine what resources the Service Graph Connector will import into the CMDB. While you could use a user API token, it could import resources from multiple organizations. By providing a team API token, you can scope permissions to only import resources from specified workspaces within a single organization. + +To create a team API token: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to create a team token. +2. Choose **Settings** from the sidebar, then **Teams**. +3. In **Team API Token** section, click **Create a team token**. + +Save this token in a safe place since HCP Terraform only displays it once. You will use it to configure ServiceNow in the next section. + +![ServiceNow Service Graph Connector Configure Team API token in HCP Terraform](/img/docs/service-now-service-graph-team-token-gen.png) + +### Configure Service Graph Connector for Terraform API token + +In the top navigation of your ServiceNow instance's control panel, click on **All**, search for **Service Graph Connector for Terraform**, and click **SG-Setup**. Next, click **Get Started**. + +Next, in the **Configure the Terraform connection** section, click **Get Started**. + +In the **Configure Terraform authentication credentials** section, click **Configure**. + +If you want to route traffic between your HCP Terraform and the ServiceNow instance through a MID server acting as a proxy, change the **Applies to** dropdown to "Specific MID servers" and select your previously configured MID server name. If you don't use MID servers, leave the default value. + +Set the **API Key** to the HCP Terraform team API token that you created in the previous section and click **Update**. + +![ServiceNow Service Graph Connector API Key Credentials configuration screen. The API key is provided, then saved by clicking the Update button](/img/docs/service-now-service-graph-apikey.png) + +In the **Configure Terraform authentication credentials** section, click **Mark as Complete**. + +### Configure Terraform Webhook Notification token + +To improve security, HCP Terraform includes an HMAC signature on all "generic" webhook notifications using a user-provided **token**. This token is an arbitrary secret string that HCP Terraform uses to sign each webhook notification. ServiceNow uses the same token to verify the request authenticity. Refer to [Notification Authenticity](/terraform/enterprise/api-docs/notification-configurations#notification-authenticity) for more information. + +Create a token and save it in a safe place. This secret token can be any value but should be treated as sensitive. + +In the **Configure Terraform Webhook token** section, click **Configure**. In the **Token** field, enter the secret token that will be shared between the HCP Terraform and your ServiceNow instance and click **Update**. + +![ServiceNow Service Graph Connector Webhook token configuration screen. The Token is provided, then saved by clicking the Update button](/img/docs/service-now-service-graph-webhook-token.png) + +In the **Configure Terraform Webhook token** section, click **Mark as Complete**. + +### Configure Terraform connection + +In the **Configure Terraform connection** section, click **Configure**. + +If you are using Terraform Enterprise, set the **Connection URL** to the URL of your Terraform Enterprise instance. If you are using HCP Terraform, leave the **Connection URL** as the default value of `https://app.terraform.io`. + +![ServiceNow Service Graph Connector HTTP Connection configuration screen. A Terraform Enterprise URL may be provided in the Connection URL field, the saved by clicking the Update button](/img/docs/service-now-service-graph-tfconn.png) + +If you want to use a MID server, check **Use MID server** box, change **MID Selection** dropdown to "Specific MID sever" and select your previously configured and validated MID server. + +Click **Update** to save these settings. In the **Configure Terraform connection** section, click **Mark as Complete**. + +## Import Resources + +Refer to the documentation explaining the difference between the [two modes of import](/terraform/enterprise/integrations/service-now/service-graph#import-methods) offered by the Service Graph Connector for Terraform. Both options may be enabled, or you may choose to enable only the webhook or scheduled import. + +### Configure scheduled import + +In the **Set up scheduled import job** section of the setup form, proceed to **Configure the scheduled jobs** and click **Configure**. + +You can use the **Execute Now** option to run a single import job, which is useful for testing. The import set will be displayed in the table below the scheduled import form, after refreshing the page. Once the import is successfully triggered, click on the **Import Set** field of the record to view the logs associated with the import run, as well as its status. + +Activate the job by checking the **Activate** box. Set the **Repeat Interval** and click **Update**. Note that the import processing time depends of the number of organizations and workspaces in your HCP Terraform. Setting the import job to run frequently is not recommended for big environments. + +![ServiceNow Service Graph Connector scheduled import screen](/img/docs/service-now-service-graph-scheduled-import.png) + +You can also access the scheduler interface by searching for **Service Graph Connector for Terraform** in the top navigation menu and selecting **SG-Import Schedule**. + +### Configure Terraform Webhook + +In the top navigation, click on **All**, search for **Scheduled Imports**, and click on **Scheduled Imports**. + +Select the **SG-Terraform Scheduled Process State** record, then click **To edit the record click here**. + +Click the **Active** checkbox to enable it. Leave the default value for the **Repeat Interval** of 5 seconds. Click **Update**. + +![ServiceNow Service Graph Connector scheduled import screen showing the Active checkbox enabled](/img/docs/service-now-service-graph-webhook-schedule.png) + +Next, create the webhook in HCP Terraform. Select a workspace and click **Settings > Notifications**. Click **Create a Notification**. + +Keep the **Destination** as the default option of **Webhook**. Choose a descriptive name **Name**. + +Set the **Webhook URL** enter `https:///api/x_hashi_service_gr/sg_terraform_webhook` and replace `` with the hostname of your ServiceNow instance. + +In the **Token** field, enter the same string you provided in **Terraform Webhook token** section the of the Service Graph guided setup form. + +Under **Health Events** choose **No events**. + +Under **Run Events** choose **Only certain events** and enable notifications only on **Completed** runs. Click **Create Notification**. + +![HCP Terraform notification creation screen, showing a webhook pointing to ServiceNow which is only triggered on completed runs](/img/docs/service-now-service-graph-webhook-tfc.png) + +Trigger a run in your workspace. Once the run is successfully completed, a webhook notification request will be sent to your ServiceNow instance. + +### Monitor the import job + +By following these steps, you can track the status of import jobs in ServiceNow and verify the completion of the import process before accessing the imported resources in the CMDB. + +For scheduled imports, navigate back to the **SG-Import Schedule** interface. For webhook imports, go to the **SG-Terraform Scheduled Process State** interface. + +Under the form, you will find a table containing all registered import sets. Locate and select the relevant import set record. + +Click on the **Import Set** field to open it and view its details. The **Outbound Http Requests** tab lists all requests made by your ServiceNow instance to HCP Terraform in order to retrieve the latest Terraform state. + +Monitor the state of the import job. Wait for it to change to **Complete**, indicated by a green mark. +Once the import job is complete, you can access the imported resources in the CMDB. + +![ServiceNow Service Graph Connector: import set with successfully completed status](/img/docs/service-now-service-graph-import-set.png) + +You can also access all import sets, regardless of the import type, by navigating to **All** and selecting **Import Sets** under the **Advanced** category. + +### View resources in ServiceNow CMDB + +In the top navigation of ServiceNow, click on **All** and search for **CMDB Workspace**, and click on **CMDB Workspace**. + +Perform a search by entering a Configuration Item (CI) name in the **Search** field (for example, **Virtual Machine Instance**). CI names supported by the application are listed on the [resource mapping page](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/index.mdx new file mode 100644 index 0000000000..de34c14ddb --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/index.mdx @@ -0,0 +1,91 @@ +--- +page_title: Migrate Terraform state to Terraform Enterprise or Terraform Enterprise +description: >- + Learn how to migrate existing Terraform state to Terraform Enterprise or + Terraform Enterprise so that you can manage existing infrastructure without + de-provisioning. +source: terraform-docs-common +--- + +# Migrate Terraform state to HCP Terraform or Terraform Enterprise + +This topic describes how to migrate existing Terraform state files to HCP Terraform or Terraform Enterprise without first de-provisioning them. Refer to [State](/terraform/language/state) in the Terraform configuration language reference for additional information about Terraform state. + +## Overview + +Perform the following actions to migrate existing resources to one or more workspaces in HCP Terraform or Terraform Enterprise: + +1. Stop all Terraform operations associated with the state files. +2. Migrate Terraform state files using either the Terraform CLI or the HCP Terraform or Terraform Enterprise API. + +Use one of the following methods to migrate your state: + +1. Manually using the Terraform CLI +2. Automatically using `tf-migrate` +3. Manually using the HCP Terraform API + +## Requirements + +- Terraform v1.1 and later is required to configure the `cloud` block. For Terraform v1.0 and older, use the [`remote` backend](/terraform/language/settings/backends/remote) instead. +- Create an account on [HCP Terraform](https://app.terraform.io/) or on a [Terraform Enterprise instance](/terraform/enterprise/users-teams-organizations/users#creating-an-account). +- You must present a token linked to appropriate permissions to use the API. Refer to the following topics for additional information: + - [HCP Terraform API overview](/terraform/enterprise/api-docs) + - [Terraform Enterprise API overview](/terraform/enterprise/api-docs) + +## Stop Terraform operations + +Stop all Terraform operations associated with the state files. This may require locking or deleting CI jobs, restricting access to the state backend, and communicating with other teams. You should also only migrate state files into HCP Terraform or Terraform Enterprise workspaces that have never performed a run. + +## Migrate state using the CLI + +> **Hands-on:** Complete the [Migrate State to HCP Terraform](/terraform/tutorials/state/cloud-migrate) tutorial for additional guidance on how to migrate Terraform state using the CLI. + +1. Add the `cloud` block to your Terraform configuration and specify the following fields: + + 1. `hostname` field: Specify either `app.terraform.io` for HCP Terraform or the hostname of your Terraform Enterprise deployment. + 2. `organization` field: Specify your HCP Terraform or Terraform Enterprise organization. + 3. `workspaces` block: Add a `tags` or `name` field and specify one or more destination workspaces as a list of strings. + + Refer to [The `cloud` Block](/terraform/cli/cloud/settings#the-cloud-block) in the Terraform CLI documentation for additional information. The following example migrates the state associated with the configuration to the `networking` workspace on HCP Terraform: + + ```hcl + terraform { + cloud { + hostname = "app.terraform.io" + organization = "my-org" + workspaces { + tags = ["networking"] + } + } + } + ``` + +2. Run `terraform init`. Terraform creates any workspaces specified in the configuration if they do not already exist in the organization. + +## Migrate state using Terraform migrate + +You can use the Terraform migrate CLI tool to automatically migrate state to HCP Terraform and Terraform Enterprise. The tool does not ship with HCP Terraform. You must download and install the binary for the CLI tool separately. Refer to the [Terraform migrate documentation](/terraform/enterprise/migrate/tf-migrate) for more information. + +## Migrate state using the API + +1. Encode your state files as a base64 string and generate an MD5 hash. The following example generates the string and hash file for a single `terraform.tfstate` file: + + ```shell-session + $ cat terraform.tfstate | base64 + dGVycmFmb3JtLnRmc3RhdGUK + $ md5sum terraform.tfstate + 690a3f8ae079c629494a52c68757d585 terraform.tfstate + ``` +2. If the workspace does not yet exist in your organization, send a `POST` request to the `/organizations/:organization_name/workspaces` endpoint to create it. Otherwise, proceed to the next step. Refer to the following topics for details: + - [Create a workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) in the HCP Terraform API reference documentation. + - [Create a workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) in the Terraform Enterprise API reference documentation. +3. Send a `POST` request to the `/workspaces/:workspace_id/actions/lock` endpoint to lock the workspace. Refer to the following topics for details: + - [Lock a workspace](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) in the HCP Terraform API reference documentation. + - [Lock a workspace](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) in the Terraform Enterprise API reference documentation. +4. To upload your state files to the workspace, send a `POST` request to the `/workspaces/:workspace_id/state-versions` endpoint. Specify the MD5 string in the `data.attributes.md5` field and encoded state file in the `data.attributes.state` field of the request body. Refer to the following topics for details: + - [Create a state version](/terraform/enterprise/api-docs/state-versions#create-a-state-version) in the HCP Terraform API reference documentation. + - [Create a state version](/terraform/enterprise/api-docs/state-versions#create-a-state-version) in the Terraform Enterprise API reference documentation. +5. Send a `POST` request to the `/workspaces/:workspace_id/actions/unlock` endpoint to unlock the workspace. + +Refer to the following external article for an example of how to create a script in Python to automate multiple state files: +[Migrating A Lot of State with Python and the HCP Terraform (previously Terraform Cloud) API](https://medium.com/hashicorp-engineering/migrating-a-lot-of-state-with-python-and-the-terraform-cloud-api-997ec798cd11). The example uses the [Workspaces API](/terraform/enterprise/api-docs/workspaces#create-a-workspace) to create the necessary workspaces in HCP Terraform and the [State Versions API](/terraform/enterprise/api-docs/state-versions) to migrate the state files to those workspaces. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/index.mdx new file mode 100644 index 0000000000..9712d3e465 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/index.mdx @@ -0,0 +1,132 @@ +--- +page_title: Terraform migrate overview +description: Learn how to install and configure the Terraform migrate tf-migrate CLI tool. +source: terraform-docs-common +--- + +# Terraform migrate + +The Terraform migrate `tf-migrate` CLI automatically migrates your Terraform Community Edition state and variables to HCP Terraform or Terraform Enterprise. It also updates your local configuration with the new state storage location and optionally creates a pull request to update your code repository. + +**Hands-on**: Complete the [Migrate to HCP Terraform in bulk](/terraform/tutorials/cloud/bulk-migrate-hcp) tutorial to get started with `tf-migrate`. + +## Overview + +Complete the following steps to install and configure `tf-migrate`: + +1. [Download and install `tf-migrate`](#install). +2. Configure `tf-migrate` to [authenticate](#connect-to-hcp-terraform-or-enterprise-terraform) to HCP Terraform or Terraform Enterprise. +3. Enable logging so that you can troubleshoot potential issues that may occur during the migration process. + +### GitHub and GitLab connection requirements + +The `tf-migrate` tool can optionally open a pull request to update your configuration in GitHub or GitLab. + +If your Terraform files are stored in GitHub, you must configure an API token that meets the following requirements: + +- The token must be a classic token. Refer to the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for additional information. +- The token must have the `repo` OAuth scope. + +If your Terraform files are stored in GitLab Cloud, you must configure an API token that meets the following requirements: + +- The token must be a personal access token. Refer to the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for additional information. +- The token must be have `read_repository` and `write_repository` scopes. + +## Install + + + + + +HashiCorp distributes `tf-migrate` as a binary package. To install `tf-migrate`, find the [appropriate binary](https://releases.hashicorp.com/tf-migrate/) for your operating system and download it as a zip archive. + +After you download `tf-migrate`, unzip the archive. + +Finally, make sure that the `tf-migrate` binary is available in a directory that is in your system's `PATH`. + +### Verify the installation + +Every build of `tf-migrate` includes a `SHA256SUMS` and a `SHA256SUMS.sig` file to validate your downloaded binary. Refer to the [verify HashiCorp binary downloads tutorial](https://developer.hashicorp.com/well-architected-framework/operational-excellence/verify-hashicorp-binary) for more information. + + + + + +[Homebrew](https://brew.sh/) is a free and open-source package management system for macOS. You can install the official [`tf-migrate`](https://github.com/hashicorp/homebrew-tap) formula from the terminal. + +First, install the HashiCorp tap, a repository of all our Homebrew packages. + + $ brew tap hashicorp/tap + +Now, install `tf-migrate` with the `hashicorp/tap/tf-migrate` formula. + + $ brew install hashicorp/tap/tf-migrate + + + + + +## Connect to HCP Terraform or Enterprise Terraform + +The `tf-migrate` tool uses your locally configured Terraform CLI API token. If you have not authenticated your local Terraform installation with HCP Terraform, use the `terraform login` command to create an authentication token. + + $ terraform login + + Terraform will request an API token for app.terraform.io using your browser. + + If login is successful, Terraform will store the token in plain text in + the following file for use by subsequent commands: + /Users/redacted/.terraform.d/credentials.tfrc.json + + Do you want to proceed? + Only 'yes' will be accepted to confirm. + + Enter a value: yes + +Terraform opens a browser to the HCP Terraform sign in screen, where you can then enter a token name in the web UI, or leave the default name. Click **Create API token** to generate the authentication token. + +HCP Terraform only displays your token once. Copy this token, then when the Terraform CLI prompts you, paste the user token exactly once into your terminal. Press **Enter** to complete the authentication process. + +`tf-migrate` can optionally create a pull request that updates the state storage location specified in your Terraform configuration. To do this, `tf-migrate` uses the GitHub or GitLab Cloud API, and requires an API token with permissions to modify your Git repository. + +To configure your API token, set the `TF_GIT_PAT_TOKEN` environment variable + + $ export TF_GIT_PAT_TOKEN= + +## Supported backends + +The `tf-migrate` tool supports migrating state from the following backends to HCP Terraform or Terraform Enterprise: + +- [local](/terraform/language/backend/local) +- [azurerm](/terraform/language/backend/azurerm) +- [consul](/terraform/language/backend/consul) +- [cos](/terraform/language/backend/cos) +- [gcs](/terraform/language/backend/gcs) +- [http](/terraform/language/backend/http) +- [Kubernetes](/terraform/language/backend/kubernetes) +- [oss](/terraform/language/backend/oss) +- [pg](/terraform/language/backend/pg) +- [s3](/terraform/language/backend/s3) + +`tf-migrate` does not support migrating state from an existing `cloud` integration or `remote` backend. + +## Enable logging + +You can enable detailed logging by setting the `TF_MIGRATE_ENABLE_LOG` environment variable to `true`. When you enable this setting, `tf-migrate` writes the logs to the following locations, depending on your operating system: + +| Platform | Location | +| --------------- | --------------------------------------------------------------- | +| macOS and Linux | `/Users//.tf-migrate/logs//.log` | +| Windows | `C:\Users\\.tf-migrate\logs\\.log` | + +You can set the `TF_MIGRATE_LOG_LEVEL` environment variable to one of the following values to change the verbosity of the logs in order of decreasing verbosity: + +- `TRACE` +- `DEBUG` +- `INFO` +- `WARN` +- `ERROR` + +## Additional configuration + +You can create an optional configuration file to modify the `tf-migrate` CLI behavior and specify the path to the configuration file when you run `tf-migrate prepare`. Any command-line flags you provide with these commands override the configuration file. Refer to the [configuration reference](/terraform/enterprise/migrate/tf-migrate/reference/configuration) for additional information. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/configuration.mdx new file mode 100644 index 0000000000..215f5b9a2b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/configuration.mdx @@ -0,0 +1,88 @@ +--- +page_title: Configuration file reference +description: >- + You can configure `tf-migrate` to control how it migrate your state to + Terraform Enterprise or Terraform Enterprise. +source: terraform-docs-common +--- + +# `tf-migrate` configuration file reference + +This topic describes the parameters for configuring the `tf-migrate` CLI. + +## Configuration model + +A `tf-migrate` configuration file supports the following parameters. + +- [`skip-dir`](#skip-dir): list of strings +- [`projects`](#projects): list of objects + - [`dir`](#projects-dir): string + - [`workspaces`](#projects-workspaces): list of objects + - [`name`](#projects-workspaces): string + - [`env-vars`](#projects-workspaces): + - [`terraform-vars`](#projects-workspaces): list of strings + +## Specification + +This section provides details about the fields you can configure in a `tf-migrate` configuration file. + +### `skip-dir` + +Specifies a list of paths to directories you want `tf-migrate` to skip. This parameter is identical to using the [`-skip-dir` command-line flag](/terraform/enterprise/migrate/tf-migrate/reference/prepare#available-options). By default, `tf-migrate` processes all child directories containing Terraform configuration files. + +- Data type: List of strings +- Default: None + +### `projects` + +Specifies a list of project configurations that align with local directories. The `tf-migrate` tool creates one project in HCP Terraform or Terraform Enterprise per configuration. In each project, `tf-migrate` creates one workspace per local workspace. + +- Data type: List of objects +- Default: None + +### `projects.dir` + +Specifies the relative or absolute path to the Terraform configuration to migrate. + +- Data type: String +- Default: None + +### `projects.workspaces` + +Specifies workspace configurations in the project. Terraform creates a workspace in HCP Terraform or Terraform Enterprise for each workspace configuration. The following table describes the attributes you can configure in each item in the list of workspaces: + +| Attribute | Description | Data type | Default | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------- | +| `name` | Specifies the name of the local workspace. | String | None | +| `env-vars` | Specifies a map of environment variables to set during the migration. Each key must start with `TF_VAR`. You must specify `env-vars`, `terraform-vars`, or both. | Object | None | +| `terraform-vars` | Specifies a list of Terraform variables files to use for configuring the workspace. Each file must end with either `.tfvars` or `tfvars.json`. You must specify `terraform-vars`, `env-vars`, or both. The path can be a relative or absolute path. | List of strings | None | + +- Data type: List of objects +- Default: None + +## Example configuration file + +In the following example, Terraform creates one project using data from the `example/project1` directory. The project has a workspace named `staging` and a workspace named `dev`: + +```hcl +skip-dir = ["example/skip/dir1", "example/skip/dir2"] + +projects = [ + { + dir = "example/project1" + workspaces = [ + { + name = "staging" + env-vars = { + "TF_VAR_region": "us-east-2" + } + terraform-vars = ["staging.tfvars"] + }, + { + name = "dev" + terraform-vars = ["dev.tfvars"] + } + ] + } +] +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/execute.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/execute.mdx new file mode 100644 index 0000000000..511175e82a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/execute.mdx @@ -0,0 +1,65 @@ +--- +page_title: tf-migrate execute reference +description: >- + The `tf-migrate execute` command runs a prepared migration to migrate locally + existing state to Terraform Enterprise or Terraform Enterprise. +source: terraform-docs-common +--- + +# `tf-migrate execute` reference + +The `tf-migrate execute` command directs Terraform to run the `init`, `plan`, and `apply` commands on the configuration generated with the `tf-migrate prepare` command. + +## Usage + + $ tf-migrate execute + +## Description + +The `tf-migrate execute` command creates the project and workspace in HCP Terraform or Terraform Enterprise, migrates the existing state, and updates your configuration to replace the `backend` block with the `cloud` block. If you responded to the prompt in the prepare workflow to create a pull request, `tf-migrate` creates the pull request after it completes the migration. + +When Terraform migrate completes the migration, it displays the number of workspaces migrated, a link to each HCP Terraform workspace, and a link to the GitHub pull request if you configured it to create one. + +## Example + +The `tf-migrate execute` command automatically performs the migration and code updates. + + + + $ tf-migrate execute + ✓ Init command ran successfully + ✓ Plan command ran successfully and changes are detected + ✓ Apply command ran successfully + Apply complete! Resources: 7 added, 0 changed, 0 destroyed. + + + Migration Summary + ┌───────────────────────────────┬───────┐ + │ Metric │ Count │ + ├───────────────────────────────┼───────┤ + │ Number of Projects Migrated │ 2 │ + │ Number of Directories Skipped │ 0 │ + │ Number of New Workspaces │ 2 │ + │ Number of Variables Migrated │ 8 │ + └───────────────────────────────┴───────┘ + ┌───────────────────────────────────────────────────────────────────────────────────────────────────┐ + │ Workspace URLs │ + ├───────────────────────────────────────────────────────────────────────────────────────────────────┤ + │ https://app.terraform.io//workspaces/web_default │ + │ https://app.terraform.io//workspaces/api_default │ + └───────────────────────────────────────────────────────────────────────────────────────────────────┘ + ┌────────────────────────────────────────────────────────────────────────┐ + │ Pull Request Link │ + ├────────────────────────────────────────────────────────────────────────┤ + │ https://github.com//learn-terraform-migrate/pull/1 │ + └────────────────────────────────────────────────────────────────────────┘ + + + +## Available options + +You can include the following flags when you run the `tf-migrate execute` command: + +| Option | Description | Default | Required | +| ---------- | ------------------------------------------------------------------------------------------------------------------- | ------- | -------- | +| `-dry-run` | If set, Terraform migrate only shows the output from the `terraform plan` step, and does not perform the migration. | None | No | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/prepare.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/prepare.mdx new file mode 100644 index 0000000000..ae735703bf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/migrate/tf-migrate/reference/prepare.mdx @@ -0,0 +1,104 @@ +--- +page_title: tf-migrate prepare reference +description: >- + The `tf-migrate prepare` command gathers information and creates a plan to + migrate your Terraform Community Edition state. +source: terraform-docs-common +--- + +# `tf-migrate prepare` reference + +The `tf-migrate prepare` command recursively scans the current directory for Terraform state files, then generates new Terraform configuration to migrate the state to HCP Terraform or Terraform Enterprise. + +## Usage + + $ tf-migrate prepare [options] + +## Description + +The `tf-migrate prepare` command prompts you for the following information: + +- The HCP Terraform or Terraform Enterprise organization to migrate your state to. +- If you would like to create a new branch named `hcp-migrate-` where `` is the name of the branch you currently have checked out. +- If you would like it to automatically create a pull request with the updated code change when the migration is complete. + +The `tf-migrate prepare` command generates a new Terraform configuration in the `_hcp-migrate-configs` directory to perform the migration. This configuration creates the following resources: + +- One workspace per state file. The `tf-migrate` tool names the workspace following the `-` pattern. The `tf-migrate` tool also creates workspace variables from the Terraform configuration's variables. +- One project to store all workspaces. The `tf-migrate` tool uses the directory path to the state file as the project name. For example, if your configuration is stored at `./frontend/networking/terraform.tfstate`, `tf-migrate` names the project "frontend_networking". Because of this, your directory path must be between 3-40 characters and only include letters, numbers, inner spaces, hyphens, and underscores. +- A new local git branch if you responded to the prompt to create a new branch with `yes`. +- A new pull request in the remote git repository if you responded to the prompt to create a pull request with `yes`. + +The `tf-migrate` CLI tool adds the generated configuration to the `.gitignore` file so that the configuration is not committed to source control. + +The `tf-migrate` tool creates the following structure in HCP Terraform or Terraform Enterprise depending on your local configuration: + +| Source | Result | +| :------------------------------------------------------------------------- | :----------------------------------------------------------- | +| Single configuration, single state | Single HCP workspace | +| Single configuration, multiple states for each Community Edition workspace | One HCP workspace per state | +| Multiple configurations, one state per configuration | One HCP workspace per configuration | +| Multiple configurations, multiple states per configuration | One HCP workspace per combination of configuration and state | + +## Example + +The `tf-migrate prepare` command generates the configuration to migrate this state to a single HCP Terraform workspace. + + + + $ tf-migrate prepare + ✓ Current working directory: /tmp/learn-terraform-migrate + ✓ Environment readiness checks completed + ✓ Found 3 HCP Terraform organizations + ┌────────────────────────────┐ + │ Available Orgs │ + ├────────────────────────────┤ + │ my-org-1 │ + │ my-org-2 │ + │ my-org-3 │ + └────────────────────────────┘ + Enter the name of the HCP Terraform organization to migrate to: my-org-1 + ✓ You have selected organization my-org-1 for migration + ✓ Found 2 directories with Terraform files + ┌────────────────────────────────┐ + │ Terraform File Directories │ + ├────────────────────────────────┤ + │ web │ + │ api │ + └────────────────────────────────┘ + Create a local branch named hcp-migrate-main from the current branch main: ... ? + + + Only 'yes or no' will be accepted as input. + Type 'yes' to approve the step + Type 'no' to to skip + + + Enter a value: yes + + ✓ Successfully created branch hcp-migrate-main + Do you want to open a pull request from hcp-migrate-main ... ? + + + Only 'yes or no' will be accepted as input. + Type 'yes' to approve the step + Type 'no' to to skip + + + Enter a value: yes + + ✓ Migration config generation completed + ✓ Successfully updated .gitignore + + + +## Available options + +You can include the following flags when you run the `tf-migrate prepare` command: + +| Option | Description | Default | Required | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- | +| `-config` | Specifies the path to an optional configuration file. Refer to [`tf-migrate` configuration file reference](/terraform/enterprise/migrate/tf-migrate/reference/configuration) for more information. | None | No | +| `-hostname` | The hostname of your Terraform Enterprise server. If you do not provide a hostname, `tf-migrate` defaults to HCP Terraform. | `app.terraform.io` | No | +| `-skip-dir` | Specifies a comma-separated list of relative paths to exclude from the migration. | None | No | +| `--parallelism` | Specifies the number of threads `tf-migrate` uses to scan the local directory and prepare the migration. Set this value to `1` to disable parallelism. | The number of logical CPUs in the system. | No | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/no-code-provisioning/module-design.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/no-code-provisioning/module-design.mdx new file mode 100644 index 0000000000..8b62ff5f99 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/no-code-provisioning/module-design.mdx @@ -0,0 +1,72 @@ +--- +page_title: Design no-code ready modules for Terraform Enterprise +description: >- + No-code ready modules let users deploy a module's resources without writing + configuration. Learn how to prepare modules for no-code provisioning. +source: terraform-docs-common +--- + +# Design no-code ready modules + +Terraform [modules](/terraform/language/modules) let you define standardized collections of infrastructure resources that downstream users can more easily deploy. No-code ready modules build on these advantages by letting users deploy a module's resources without writing any Terraform configuration. This practice is called no-code provisioning. + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +No-code provisioning enables a self-service workflow that lets users provision approved collections of resources without learning Terraform or infrastructure best practices. You can enable no-code provisioning for any public or private module in your [private registry](/terraform/enterprise/registry). Users can then [provision no-code infrastructure](/terraform/enterprise/no-code-provisioning/provisioning), set the module's input variables, and deploy its resources. + +> **Hands On:** Try the [Create and Use No-Code Ready Modules tutorial](/terraform/tutorials/cloud/no-code-provisioning). + +The same best practices apply to both standard and no-code ready module design. However, no-code modules have additional requirements and considerations. + +## Requirements + +A no-code ready module must meet the following requirements: + +- **Root Module Structure:** The module must follow [standard module structure](/terraform/language/modules/develop/structure) and define its resources in the root directory of the repository. This structure allows the public and private registries to generate documentation, track resource usage, and parse submodules and examples. +- **Provider Configuration:** A no-code ready module must declare the required provider(s) directly in the module. This configuration differs from the recommendations for [modules used in written configuration](/terraform/language/modules/develop/providers#legacy-shared-modules-with-provider-configurations). + +### Provider credentials + +Organization administrators must determine how no-code workspaces access credentials for provider authentication and design modules accordingly. + +When module consumers follow the no-code workflow, HCP Terraform automatically creates a new workspace for the resources and attempts to provision them. New workspaces must be able to access credentials for all providers defined within the module. + +You can grant new no-code workspace provider credentials using one of the following methods: + +- Recommended: Create a [project-scoped variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) that HCP Terraform applies to all existing and future workspaces within a project. This approach allows you to create specific teams for those less familiar with Terraform, then give those teams access to your no-code projects. +- Create a [global variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) that HCP Terraform applies to all existing and future workspaces in the organization. This action automatically grants newly-created workspaces access to the required provider credentials. +- Expose provider credentials as sensitive outputs in another workspace. You must add additional configuration to the module to access these values through [remote state data sources](/terraform/language/state/remote-state-data) and then reference them in provider configuration. This approach provides more control over access to these credentials than placing them in a global variable set. +- Elect to let the first run in new no-code workspaces fail and have module users add credentials directly to the workspace after creation. This approach provides the most control over access to provider credentials, but requires manual intervention. Module users must manually start a new run to provision infrastructure after they configure the credentials. + +## Module Design Recommendations + +Similarly to a [standard module](/terraform/language/modules/develop#when-to-write-a-module), a well-designed no-code ready module composes resources so that they are easy for others to deploy. However, no-code module users are less familiar with Terraform, so we recommend the following best practices for no-code module design. + +### Build For a Specific Use Case + +No-code ready module users are typically less familiar with Terraform and infrastructure management. Reduce the amount of technical decision-making required to deploy the module by scoping it to a single, specific use case. This approach lets users focus on business concerns instead of infrastructure concerns. + +For example, you could build modules that satisfy the following well-scoped use cases: + +- Deploying all resources needed for a three-tier web application +- Deploying a database with constraints on resource allocation and deployment region + +### Updating a Module's Version + +When you enable no-code provisioning for a module, HCP Terraform pins the **No-code Ready** designation to the specific module version of your choice. HCP Terraform deploys that selected module version whenever a user provisions a workspace using that module, ensuring that no-code users always provision the correct version. Pinning the **No-code Ready** designation to a specific module version lets you set variable input options, which are tied to that specific module version. + +By default, a module selects the latest version available. If you pinned a specific module version and a newer one becomes available, you can always update your module's version. + +### Provide Variable Defaults When Possible + +The no-code provisioning workflow prompts users to set values for the module version's input variables before creating the new workspace and deploying resources. We recommend setting reasonable defaults when possible to reduce the effort and expertise needed to deploy the module. Remember that the workspace can also access variable values set through global or project level variable sets in your organization. + +### Define Dropdown Options for Variables without Defaults + +If your module has variables without defaults, you can define options to limit the values a user can input when you enable a module for no-code provisioning. You can define input options using the HCP Terraform UI, the [No-Code Provisioning API](/terraform/enterprise/api-docs/no-code-provisioning), or the [TFE provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/no_code_module). We recommend using the TFE provider if you want to track variable input options through a code approval process, therefore keeping your configuration as code. + +HCP Terraform surfaces any subsequent changes to a variable’s input options when no-code users provision a new module version. If you update the selected module version enabled for no-code provisioning, consider revisiting the variables and adjusting the defined input values accordingly. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/no-code-provisioning/provisioning.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/no-code-provisioning/provisioning.mdx new file mode 100644 index 0000000000..46c36667f2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/no-code-provisioning/provisioning.mdx @@ -0,0 +1,89 @@ +--- +page_title: Provision no-code infrastructure in Terraform Enterprise +description: >- + No-code ready modules let users deploy a module's resources without writing + configuration. Learn how to provision infrastructure from a no-code ready + module. +source: terraform-docs-common +--- + +# Provision no-code infrastructure + +No-code provisioning lets you deploy infrastructure resources in a new HCP Terraform workspace without writing any Terraform configuration. You can create a no-code workspace from any module version labeled **No-code Ready** in your organization's [private registry](/terraform/enterprise/registry). + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +> **Hands On:** Try the [Create and Use No-Code Ready Modules tutorial](/terraform/tutorials/cloud/no-code-provisioning). + +## Permissions + +To use no-code provisioning, you must be a member of a team with [manage all projects permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects), [manage all workspaces permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces), or [admin permissions for a project](/terraform/enterprise/users-teams-organizations/permissions#project-admins). When using [custom project permissions](/terraform/enterprise/users-teams-organizations/permissions#custom-project-permissions), your team must be able to create workspaces, write variables, and apply runs in a project. + +## Provider Credentials + +Terraform automatically starts a new run to provision no-code infrastructure upon workspace creation. No-code modules contain provider blocks in their configuration, but still require provider credentials for successful deployment. Organization administrators determine how new workspaces should [access provider credentials](/terraform/enterprise/no-code-provisioning/module-design#provider-credentials), which may require specific module design. + +## Creating a Workspace and Deploying Resources + +The no-code provisioning workflow creates a new HCP Terraform workspace to deploy and manage the no-code ready module's resources. HCP Terraform automatically starts a run to provision the module's resources in the new workspace. Depending on the workspace's settings, Terraform either automatically applies the plan or prompts you for approval to provision the infrastructure. + +To launch the no-code workflow: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization with the module you want to provision. + +2. Click **Registry** in the main HCP Terraform navigation to access your organization's private registry. + +3. Click **Modules** to view the list of available modules in the private registry. You can filter for no-code ready modules in your registry. No-code enabled modules have a **No-code Ready** badge next to their names. + +4. Select the no-code ready module to view its details, then click **Provision workspace**. The **Configure module inputs** page appears. + + HCP Terraform scans the module configuration for input variables and prompts for values for any variables without defaults or undefined in an existing global variable set. Terraform requires values for these variables to successfully complete runs in the workspace. HCP Terraform performs type validation for the variable values if the module configuration specifies a type. + +5. (Optional) Set values for the input variables. If your organization has defined options for a variable's values, these options appear in a dropdown menu. You can skip this step and configure the variables later in your workspace. However, HCP Terraform does not prompt you for these values again, and your Terraform runs may fail. + +6. Click **Next: Workspace settings**. + +7. Enter a **Workspace Name**. The name must be unique within the organization and can include letters, numbers, dashes (-), and underscores (\_). Refer to the [workspace naming recommendations](/terraform/enterprise/workspaces/create#workspace-naming) for more guidance. + +8. Choose a **Project** for the workspace. Teams with access to the specified project can view the workspace automatically. Refer to [Organizing Workspaces with Projects](/terraform/enterprise/projects/manage) for more details. If the specified project contains any project-scoped variable sets, HCP Terraform automatically applies those sets to the workspace. + +9. Add an optional **Description** for the workspace. + +10. Select an apply method for the workspace. **Auto apply** automatically applies any successful runs in the workspace, including the initial run on workspace creation. **Manual apply** prompts operators to review and confirm the changes in a run. **Auto apply** is the default option for a no-code workspace. + +11. Click **Create workspace**. HCP Terraform creates a new workspace and starts a run. Depending on the apply method, it automatically applies your infrastructure or prompts you for approval to create the no-code module's resources. + +## Operations in No-Code Workspaces + +No-code workspaces have a limited feature set because you cannot access the resource configuration. However, you can edit workspace variables and settings, including notifications, permissions, and run triggers. You can use run triggers to connect the workspace to one or more source workspaces, start new runs when you change workspace variables, or queue destroy runs. + +### Updating Variables + +To change a variable's options after provisioning, go to the **Variables** section in your workspace to see your workspace's variables listed. To edit a variable: + +1. Click the ellipses next to the variable you want to edit and select **Edit**. +2. Enter your desired value and click **Save variable**. + +Start a new run in your workspace to update your existing infrastructure with your new variable value. + +### Module Version Updates + +When you [update the module version](/terraform/enterprise/no-code-provisioning/module-design#updating-a-module-s-version) designated for no-code provisioning, every workspace provisioned from the module is notified that an updated version is available on the workspace overview page. HCP Terraform does not automatically update workspaces. A workspace admin must respond to the update notification to upgrade the workspace, and HCP Terraform prompts for values for any new input variables. + +To change the version of the module that users can deploy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. + +2. Choose **Registry** from the sidebar and navigate to the module in your organization's registry. + +3. Click **Configure Settings**. + +4. Click **Edit version and variable options**. + +5. Choose the desired module version from the **Module version** dropdown. + +6. Click **Save**. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/custom-sentinel.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/custom-sentinel.mdx new file mode 100644 index 0000000000..16334c8807 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/custom-sentinel.mdx @@ -0,0 +1,260 @@ +--- +page_title: Define Sentinel policies in Terraform Enterprise +description: >- + Learn how to use the Sentinel policy language to create policies in Terraform + Enterprise. +source: terraform-docs-common +--- + +# Define Sentinel policies in HCP Terraform + +This topic describes how to create and manage custom policies using Sentinel policy language. For instructions about how to use pre-written Sentinel policies from the registry, refer to [Run pre-written Sentinel policies](/terraform/enterprise/policy-enforcement/prewritten-sentinel). + +## Overview + +To define a policy, create a file and declare an `import` function to include reusable libraries, external data, and other functions. Sentinel policy language includes several types of elements you can import using the `import` function. + +Declare and configure additional Sentinel policy language elements. The details depend on which elements you want to use in your policy. Refer to the [Sentinel documentation](/sentinel/docs) for additional information. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Declare an `import` function + +A policy can include imports that enable a policy to access reusable libraries, external data, and functions. Refer to [imports](/sentinel/docs/concepts/imports) in the Sentinel documentation for more details. + +HCP Terraform provides four imports to define policy rules for the plan, configuration, state, and run associated with a policy check. + +- [tfplan](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) - Access a Terraform plan, which is the file created as a result of the [`terraform plan` command](/terraform/cli/commands/plan). The plan represents the changes that Terraform must make to reach the desired infrastructure state described in the configuration. +- [tfconfig](/terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2) - Access a Terraform configuration. The configuration is the set of `.tf` files that describe the desired infrastructure state. +- [tfstate](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) - Access the Terraform [state](/terraform/language/state). Terraform uses state to map real-world resources to your configuration. +- [tfrun](/terraform/enterprise/policy-enforcement/import-reference/tfrun) - Access data associated with a [run in HCP Terraform](/terraform/enterprise/run/remote-operations). For example, you could retrieve the run's workspace. + +You can create mocks of these imports to use with the the [Sentinel +CLI](/sentinel/docs/commands) mocking and testing features. Refer to [Mocking Terraform Sentinel Data](/terraform/enterprise/policy-enforcement/test-sentinel) for more details. + + + +HCP Terraform does not support custom imports. + + + +## Declare additional elements + +The following functions and idioms will be useful as you start writing Sentinel +policies for Terraform. + +### Iterate over modules and find resources + +The most basic Sentinel task for Terraform is to enforce a rule on all resources +of a given type. Before you can do that, you need to get a collection of all the +relevant resources from all modules. The easiest way to do that is to copy and +use a function like the following into your policies. + +The following example uses the `tfplan` import. Refer to our [guides for other examples](https://github.com/hashicorp/terraform-guides/tree/master/governance/second-generation/common-functions) of +functions that iterate over the `tfconfig` and `tfstate` imports. + +```python +import "tfplan" +import "strings" + +# Find all resources of specific type from all modules using the tfplan import +find_resources_from_plan = func(type) { + resources = {} + for tfplan.module_paths as path { + for tfplan.module(path).resources[type] else {} as name, instances { + for instances as index, r { + # Get the address of the resource instance + if length(path) == 0 { + # root module + address = type + "." + name + "[" + string(index) + "]" + } else { + # non-root module + address = "module." + strings.join(path, ".module.") + "." + + type + "." + name + "[" + string(index) + "]" + } + # Add the instance to resources, setting the key to the address + resources[address] = r + } + } + } + return resources +} +``` + +Call the function to get all resources of a desired type by passing the +type as a string in quotation marks: + +```python +aws_instances = find_resources_from_plan("aws_instance") +``` + +This example function does several useful things while finding resources: + +- It checks every module (including the root module) for resources of the + specified type by iterating over the `module_paths` namespace. The top-level + `resources` namespace is more convenient, but it only reveals resources from + the root module. +- It iterates over the named resources and [resource + instances](/terraform/language/expressions/references#resources) + found in each module, starting with `tfplan.module(path).resources[type]` + which is a series of nested maps keyed by resource names and instance counts. +- It uses the Sentinel [`else` + operator](/sentinel/docs/language/spec#else-operator) to + recover from `undefined` values which would occur for modules that don't have + any resources of the specified type. +- It builds a flat `resources` map of all resource instances of the specified + type. Using a flat map simplifies the code used by Sentinel policies to + evaluate rules. +- It computes an `address` variable for each resource instance and uses this as + the key in the `resources` map. This allows writers of Sentinel policies to + print the full [address](/terraform/cli/state/resource-addressing) of each + resource instance that violate a policy, using the same address format used in + plan and apply logs. Doing this tells users who see violation messages exactly + which resources they need to modify in their Terraform code to comply with the + Sentinel policies. +- It sets the value of the `resources` map to the data associated with the + resource instance (`r`). This is the data that Sentinel policies apply rules + against. + +### Validate resource attributes + +Once you have a collection of resources instances of a desired type indexed by +their addresses, you usually want to validate that one or more resource +attributes meets some conditions by iterating over the resource instances. + +While you could use Sentinel's [`all` and `any` +expressions](/sentinel/docs/language/boolexpr#any-all-expressions) +directly inside Sentinel rules, your rules would only report the first violation +because Sentinel uses short-circuit logic. It is therefore usually preferred to +use a [`for` loop](/sentinel/docs/language/loops) outside +of your rules so that you can report all violations that occur. You can do this +inside functions or directly in the policy itself. + +Here is a function that calls the `find_resources_from_plan` function and +validates that the instance types of all EC2 instances being provisioned are in +a given list: + +```python +# Validate that all EC2 instances have instance_type in the allowed_types list +validate_ec2_instance_types = func(allowed_types) { + validated = true + aws_instances = find_resources_from_plan("aws_instance") + for aws_instances as address, r { + # Determine if the attribute is computed + if r.diff["instance_type"].computed else false is true { + print("EC2 instance", address, + "has attribute, instance_type, that is computed.") + } else { + # Validate that each instance has allowed value + if (r.applied.instance_type else "") not in allowed_types { + print("EC2 instance", address, "has instance_type", + r.applied.instance_type, "that is not in the allowed list:", + allowed_types) + validated = false + } + } + } + return validated +} +``` + +The boolean variable `validated` is initially set to `true`, but it is set to +`false` if any resource instance violates the condition requiring that the +`instance_type` attribute be in the `allowed_types` list. Since the function +returns `true` or `false`, it can be called inside Sentinel rules. + +Note that this function prints a warning message for **every** resource instance +that violates the condition. This allows writers of Terraform code to fix all +violations after just one policy check. It also prints warnings when the +attribute being evaluated is +[computed](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#value-computed) and does +not evaluate the condition in this case since the applied value will not be +known. + +While this function allows a rule to validate an attribute against a list, some +rules will only need to validate an attribute against a single value; in those +cases, you could either use a list with a single value or embed that value +inside the function itself, drop the `allowed_types` parameter from the function +definition, and use the `is` operator instead of the `in` operator to compare +the resource attribute against the embedded value. + +### Write Rules + +Having used the standardized `find_resources_from_plan` function and having +written your own function to validate that resources instances of a specific +type satisfy some condition, you can define a list with allowed values and write +a rule that evaluates the value returned by your validation function. + +```python +# Allowed Types +allowed_types = [ + "t2.small", + "t2.medium", + "t2.large", +] + +# Main rule +main = rule { + validate_ec2_instance_types(allowed_types) +} + +``` + +### Validate multiple conditions in a single policy + +If you want a policy to validate multiple conditions against resources of a +specific type, you could define a separate validation function for each +condition or use a single function to evaluate all the conditions. In the latter +case, you would make this function return a list of boolean values, using one +for each condition. You can then use multiple Sentinel rules that evaluate +those boolean values or evaluate all of them in your `main` rule. Here is a +partial example: + +```python +# Function to validate that S3 buckets have private ACL and use KMS encryption +validate_private_acl_and_kms_encryption = func() { + result = { + "private": true, + "encrypted_by_kms": true, + } + s3_buckets = find_resources_from_plan("aws_s3_bucket") + # Iterate over resource instances and check that S3 buckets + # have private ACL and are encrypted by a KMS key + # If an S3 bucket is not private, set result["private"] to false + # If an S3 bucket is not encrypted, set result["encrypted_by_kms"] to false + for s3_buckets as joined_path, resource_map { + #... + } + return result +} + +# Call the validation function +validations = validate_private_acl_and_kms_encryption() + +# ACL rule +is_private = rule { + validations["private"] +} + +# KMS Encryption Rule +is_encrypted_by_kms = rule { + validations["encrypted_by_kms"] +} + +# Main rule +main = rule { + is_private and is_encrypted_by_kms +} +``` + +You can write similar functions and policies to restrict Terraform configurations using the `tfconfig` import and to restrict Terraform state using the `tfstate` import. + +## Next steps + +1. Group your policies into sets and apply them to your workspaces. Refer to [Create policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets#create-policy-sets) for additional information. +2. View results and address Terraform runs that do not comply with your policies. Refer to [View results](/terraform/enterprise/policy-enforcement/view-results) for additional information. +3. You can also view Sentinel policy results in JSON format. Refer to [View Sentinel JSON results](/terraform/enterprise/policy-enforcement/view-results/json) for additional information. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/index.mdx new file mode 100644 index 0000000000..bc5881f611 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/index.mdx @@ -0,0 +1,19 @@ +--- +page_title: Define policies overview +description: >- + You can define policies using HashiCorp Sentinel or Open Policy Agent (OPA). + Learn how to define policies for governing how Terraform provisions + infrastructure. +source: terraform-docs-common +--- + +# Define policies overview + +This topic provides overview information about how to define policies as code. Policies are rules for enforcing how Terraform provisions infrastructure as code for your workspaces and projects. + +## Workflows + +You can use two policy-as-code frameworks to define fine-grained, logic-based policies: Sentinel and Open Policy Agent (OPA). Depending on the settings, policies can act as advisory warnings or firm requirements that prevent Terraform from provisioning infrastructure. + +- **Sentinel:** You define policies with the [Sentinel policy language](/sentinel/docs/concepts/language) and use imports to parse the Terraform plan, state, and configuration. Refer to [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel) for details. +- **OPA:** You define policies with the [Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/). Refer to [Defining OPA Policies](/terraform/enterprise/policy-enforcement/define-policies/opa) for details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/opa.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/opa.mdx new file mode 100644 index 0000000000..92305f8e9f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/define-policies/opa.mdx @@ -0,0 +1,259 @@ +--- +page_title: Define Open Policy Agent policies for Terraform Enterprise +description: >- + Use the Rego policy language to define Open Policy Agent (OPA) policies for + Terraform Enterprise. +source: terraform-docs-common +--- + +# Define Open Policy Agent policies for HCP Terraform + +This topic describes how to create and manage custom policies using the open policy agent (OPA) framework. Refer to the following topics for instructions on using HashiCorp Sentinel policies: + +- [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel) +- [Copy pre-written Sentinel policies](/terraform/enterprise/define-policies/prewritten-sentinel) + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Overview + +> **Hands-on:** Try the [Detect Infrastructure Drift and Enforce OPA Policies](/terraform/tutorials/cloud/drift-and-opa) tutorial. + +You can write OPA policies using the Rego policy language, which is the native query language for the OPA framework. Refer to the following topics in the [OPA documentation](https://www.openpolicyagent.org/docs/latest/policy-language/) for additional information: + +- [How Do I Write Rego Policies?](https://www.openpolicyagent.org/docs/v0.13.5/how-do-i-write-policies/) +- [Rego Policy Playground](https://play.openpolicyagent.org/) + +## OPA query + +You must write a query to identify a specific policy rule within your Rego code. The query may evaluate code from multiple Rego files. + +The result of each query must return an array, which HCP Terraform uses to determine whether the policy has passed or failed. If the array is empty, HCP Terraform reports that the policy has passed. + +The query is typically a combination of the policy package name and rule name, such as `data.terraform.deny`. + +## OPA input + +HCP Terraform combines the output from the Terraform run and plan into a single JSON file and passes that file to OPA as input. Refer to the [OPA Overview documentation](https://www.openpolicyagent.org/docs/latest/#the-input-document) for more details about how OPA uses JSON input data. + +The run data contains information like workspace details and the organization name. To access the properties from the Terraform plan data in your policies, use `input.plan`. To access properties from the Terraform run, use `input.run`. + +The following example shows sample OPA input data. + +```json +{ +"plan": { + "format_version": "1.1", + "output_changes": { + }, + "planned_values": { + }, + "resource_changes": [ + ], + "terraform_version": "1.2.7" +}, + +"run": { + "organization": { + "name": "hashicorp" + }, + "workspace": { + } +} +} +``` + +Use the [Retrieve JSON Execution Plan endpoint](/terraform/enterprise/api-docs/plans#retrieve-the-json-execution-plan) to retrieve Terraform plan output data for testing. Refer to [Terraform Run Data](#terraform-run-data) for the properties included in Terraform run output data. + +## Example Policies + +The following example policy parses a Terraform plan and checks whether it includes security group updates that allow ingress traffic from all CIDRs (`0.0.0.0/0`). + +The OPA query for this example policy is `data.terraform.policies.public_ingress.deny`. + +```rego +package terraform.policies.public_ingress + +import input.plan as plan + +deny[msg] { + r := plan.resource_changes[_] + r.type == "aws_security_group" + r.change.after.ingress[_].cidr_blocks[_] == "0.0.0.0/0" + msg := sprintf("%v has 0.0.0.0/0 as allowed ingress", [r.address]) +} +``` + +The following example policy ensures that databases are no larger than 128 GB. + +The OPA query for this policy is `data.terraform.policies.fws.database.fws_db_001.rule`. + +```rego +package terraform.policies.fws.database.fws_db_001 + +import future.keywords.in +import input.plan as tfplan + +actions := [ + ["no-op"], + ["create"], + ["update"], +] + +db_size := 128 + +resources := [resource_changes | + resource_changes := tfplan.resource_changes[_] + resource_changes.type == "fakewebservices_database" + resource_changes.mode == "managed" + resource_changes.change.actions in actions +] + +violations := [resource | + resource := resources[_] + not resource.change.after.size == db_size +] + +violators[address] { + address := violations[_].address +} + +rule[msg] { + count(violations) != 0 + msg := sprintf( + "%d %q severity resource violation(s) have been detected.", + [count(violations), rego.metadata.rule().custom.severity] + ) +} +``` + +## Test policies + +You can write tests for your policies by [mocking](https://www.openpolicyagent.org/docs/latest/policy-testing/#data-and-function-mocking) the input data the policies use during Terraform runs. + +The following example policy called `block_auto_apply_runs` checks whether or not an HCP Terraform workspace has been configured to automatically apply a successful Terraform plan. + +```rego +package terraform.tfc.block_auto_apply_runs + +import input.run as run + +deny[msg] { + run.workspace.auto_apply != false + msg := sprintf( + "HCP Terraform workspace %s has been configured to automatically provision Terraform infrastructure. Change the workspace Apply Method settings to 'Manual Apply'", + [run.workspace.name], + ) +} +``` + +The following test validates `block_auto_apply_runs`. The test is written in rego and uses the OPA [test format](https://www.openpolicyagent.org/docs/latest/policy-testing/#test-format) to check that the workspace [apply method](/terraform/enterprise/workspaces/settings#apply-method) is not configured to auto apply. You can run this test with the `opa test` CLI command. Refer to [Policy Testing](https://www.openpolicyagent.org/docs/latest/policy-testing/) in the OPA documentation for more details. + +```rego +package terraform.tfc.block_auto_apply_runs + +import future.keywords + +test_run_workspace_auto_apply if { + deny with input as {"run": {"workspace": {"auto_apply": true}}} +} +``` + +## Terraform run data + +Each [Terraform run](/terraform/docs/glossary#run) outputs data describing the run settings and the associated workspace. + +### Schema + +The following code shows the schema for Terraform run data. + + run + ├── id (string) + ├── created_at (string) + ├── created_by (string) + ├── message (string) + ├── commit_sha (string) + ├── is_destroy (boolean) + ├── refresh (boolean) + ├── refresh_only (boolean) + ├── replace_addrs (array of strings) + ├── speculative (boolean) + ├── target_addrs (array of strings) + └── project + │ ├── id (string) + │ └── name (string) + ├── variables (map of keys) + ├── organization + │ └── name (string) + └── workspace + ├── id (string) + ├── name (string) + ├── created_at (string) + ├── description (string) + ├── execution_mode (string) + ├── auto_apply (bool) + ├── tags (array of strings) + ├── working_directory (string) + └── vcs_repo (map of keys) + +### Properties + +The following sections contain details about each property in Terraform run data. + +#### Run namespace + +The following table contains the attributes for the `run` namespace. + +| Properties Name | Type | Description | +| --------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | String | The ID associated with the current Terraform run | +| `created_at` | String | The time Terraform created the run. The timestamp follows the [standard timestamp format in RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). | +| `created_by` | String | A string that specifies the user name of the HCP Terraform user for the specific run. | +| `message` | String | The message associated with the Terraform run. The default value is "Queued manually via the Terraform Enterprise API". | +| `commit_sha` | String | The checksum hash (SHA) that identifies the commit | +| `is_destroy` | Boolean | Whether the plan is a destroy plan that destroys all provisioned resources | +| `refresh` | Boolean | Whether the state refreshed prior to the plan | +| `refresh_only` | Boolean | Whether the plan is in refresh-only mode. In refresh-only mode, Terraform ignores configuration changes and updates state with any changes made outside of Terraform. | +| `replace_addrs` | An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing) | The targets specified using the [`-replace`](/terraform/cli/commands/plan#replace-address) flag in the CLI or the `replace-addrs` property in the API. Undefined if there are no specified resource targets. | +| `speculative` | Boolean | Whether the plan associated with the run is a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) only | +| `target_addrs` | An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing). | The targets specified using the [`-target`](/terraform/cli/commands/plan#resource-targeting) flag in the CLI or the `target-addrs` property in the API. Undefined if there are no specified resource targets. | +| `variables` | A string-keyed map of values. | Provides the variables configured within the run. Each variable `name` maps to two properties: `category` and `sensitive`. The `category` property is a string indicating the variable type, either "input" or "environment". The `sensitive` property is a boolean, indicating whether the variable is a [sensitive value](/terraform/enterprise/workspaces/variables/managing-variables#sensitive-values). | + +#### Project Namespace + +The following table contains the properties for the `project` namespace. + +| Property Name | Type | Description | +| ------------- | ------ | --------------------------------------------------------------------------------------- | +| `id` | String | The ID associated with the Terraform project | +| `name` | String | The name of the project, which can only include letters, numbers, spaces, `-`, and `_`. | + +#### Organization namespace + +The `organization` namespace has one property called `name`. The `name` property is a string that specifies the name of the HCP Terraform organization for the run. + +#### Workspace namespace + +The following table contains the properties for the `workspace` namespace. + +| Property Name | Type | Description | +| ------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | String | The ID associated with the Terraform workspace | +| `name` | String | The name of the workspace, which can only include letters, numbers, `-`, and `_` | +| `created_at` | String | The time of the workspace's creation. The timestamp follows the [standard timestamp format in RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). | +| `description` | String | The description for the workspace. This value can be `null`. | +| `auto_apply` | Boolean | The workspace's [auto-apply](/terraform/enterprise/workspaces/settings#apply-method) setting | +| `tags` | Array of strings | The list of tag names for the workspace | +| `working_directory` | String | The configured [Terraform working directory](/terraform/enterprise/workspaces/settings#terraform-working-directory) of the workspace. This value can be `null`. | +| `execution_mode` | String | The configured Terraform execution mode of the workspace. The default value is `remote`. | +| `vcs_repo` | A string-keyed map to objects | Data associated with a VCS repository connected to the workspace. The map contains `identifier` (string), ` display_identifier` (string), `branch` (string), and `ingress_submodules` (boolean). Refer to the HCP Terraform [Workspaces API documentation](/terraform/enterprise/api-docs/workspaces) for details about each property. This value can be `null`. | + +## Next steps + +- Group your policies into sets and apply them to your workspaces. Refer to [Create policy sets](/policy-enforcement/manage-policy-sets#create-policy-sets) for additional information. +- View results and address Terraform runs that do not comply with your policies. Refer to [View results](/terraform/enterprise/policy-enforcement/view-results) for additional information. +- You can also view Sentinel policy results in JSON format. Refer to [View Sentinel JSON results](/terraform/enterprise/policy-enforcement/view-results/json) for additional information. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/index.mdx new file mode 100644 index 0000000000..eebf3b47f7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/index.mdx @@ -0,0 +1,32 @@ +--- +page_title: Sentinel import function reference +description: >- + Use the Sentinel import function to configure policy behaviors in custom + Sentinel policies. +source: terraform-docs-common +--- + +# `import` function reference overview + +This topic provides an overview of the Sentinel `import` function, which you can use to import Sentinel libraries into your custom Sentinel policies. Refer to [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel) for additional information about how to use the `import` function. + +## Functions for Terraform + +You can add Sentinel the `import` function, which enables a policy to access reusable libraries, external data, and other functions. Refer to the [Sentinel imports documentation](/sentinel/docs/language/imports) for more details. + +HCP Terraform provides the following importable libraries to define policy rules for the plan, configuration, state, and run associated with a policy check. + +- [`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan) : Provides access to a Terraform plan, which is the file created when you run the `terraform plan` command. This library is deprecated. Use `tfplanv/2` instead. +- [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2): Provides access to a Terraform plan, which is the file created when you run the `terraform plan` command. +- [`tfconfig`](/terraform/enterprise/policy-enforcement/import-reference/tfconfig): Provides access to a Terraform configuration. The configuration is the set of `.tf` files that describe the desired infrastructure state. This library is deprecated. Use `tfconfig/v2` instead. +- [`tfconfig/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2): Provides access to a Terraform configuration. The configuration is the set of `.tf` files that describe the desired infrastructure state. +- [`tfstate`](/terraform/enterprise/policy-enforcement/import-reference/tfstate): Provides access to the Terraform state. Terraform uses state to map real-world resources to your configuration. This library is deprecated. Use `tfstate/v2` instead. +- [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2): Provides access to the Terraform state. Terraform uses state to map real-world resources to your configuration. +- [`tfrun`](/terraform/enterprise/policy-enforcement/import-reference/tfrun): Provides access to data associated with a run in HCP Terraform. For example, you could retrieve the run's workspace. + +## Test `import` functions + +You can create mocks of these functions and test them using the Sentinel CLI. Refer to the following topics for additional information: + +- [Test Sentinel policies](/terraform/enterprise/policy-enforcement/test-sentinel) +- [Sentinel CLI documentation](/sentinel/docs/commands) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfconfig-v2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfconfig-v2.mdx new file mode 100644 index 0000000000..637d596f01 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfconfig-v2.mdx @@ -0,0 +1,422 @@ +--- +page_title: tfconfig/v2 Sentinel import +description: >- + Use the tfconfig/v2 import to give Sentinel access to a Terraform + configuration. +source: terraform-docs-common +--- + +-> **Note:** This is documentation for the next version of the `tfconfig` +Sentinel import, designed specifically for Terraform 0.12. This import requires +Terraform 0.12 or higher, and must currently be loaded by path, using an alias, +example: `import "tfconfig/v2" as tfconfig`. + +# tfconfig/v2 Sentinel import + +The `tfconfig/v2` import provides access to a Terraform configuration. + +The Terraform configuration is the set of `*.tf` files that are used to +describe the desired infrastructure state. Policies using the `tfconfig` +import can access all aspects of the configuration: providers, resources, +data sources, modules, and variables. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Some use cases for `tfconfig` include: + +- **Organizational naming conventions**: requiring that configuration elements + are named in a way that conforms to some organization-wide standard. +- **Required inputs and outputs**: organizations may require a particular set + of input variable names across all workspaces or may require a particular + set of outputs for asset management purposes. +- **Enforcing particular modules**: organizations may provide a number of + "building block" modules and require that each workspace be built only from + combinations of these modules. +- **Enforcing particular providers or resources**: an organization may wish to + require or prevent the use of providers and/or resources so that configuration + authors cannot use alternative approaches to work around policy + restrictions. + +The data in the `tfconfig/v2` import is sourced from the JSON configuration file +that is generated by the [`terraform show -json`](/terraform/cli/commands/show#json-output) command. For more information on +the file format, see the [JSON Output Format](/terraform/internals/json-format) +page. + +## Import Overview + +The `tfconfig/v2` import is structured as a series of _collections_, keyed as a +specific format, such as resource address, module address, or a +specifically-formatted provider key. + + tfconfig/v2 + ├── strip_index() (function) + ├── providers + │ └── (indexed by [module_address:]provider[.alias]) + │ ├── provider_config_key (string) + │ ├── name (string) + │ ├── full_name (string) + │ ├── alias (string) + │ ├── module_address (string) + │ ├── config (block expression representation) + │ └── version_constraint (string) + ├── resources + │ └── (indexed by address) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── provider_config_key (string) + │ ├── provisioners (list) + │ │ └── (ordered provisioners for this resource only) + │ ├── config (block expression representation) + │ ├── count (expression representation) + │ ├── for_each (expression representation) + │ └── depends_on (list of strings) + ├── provisioners + │ └── (indexed by resource_address:index) + │ ├── resource_address (string) + │ ├── type (string) + │ ├── index (string) + │ └── config (block expression representation) + ├── variables + │ └── (indexed by module_address:name) + │ ├── module_address (string) + │ ├── name (string) + │ ├── default (value) + │ └── description (string) + ├── outputs + │ └── (indexed by module_address:name) + │ ├── module_address (string) + │ ├── name (string) + │ ├── sensitive (boolean) + │ ├── value (expression representation) + │ ├── description (string) + │ └── depends_on (list of strings) + └── module_calls + └── (indexed by module_address:name) + ├── module_address (string) + ├── name (string) + ├── source (string) + ├── config (block expression representation) + ├── count (expression representation) + ├── depends_on (expression representation) + ├── for_each (expression representation) + └── version_constraint (string) + +The collections are: + +- [`providers`](#the-providers-collection) - The configuration for all provider + instances across all modules in the configuration. +- [`resources`](#the-resources-collection) - The configuration of all resources + across all modules in the configuration. +- [`variables`](#the-variables-collection) - The configuration of all variable + definitions across all modules in the configuration. +- [`outputs`](#the-outputs-collection) - The configuration of all output + definitions across all modules in the configuration. +- [`module_calls`](#the-module_calls-collection) - The configuration of all module + calls (individual [`module`](/terraform/language/modules) blocks) across + all modules in the configuration. + +These collections are specifically designed to be used with the +[`filter`](/sentinel/docs/language/collection-operations#filter-expression) +quantifier expression in Sentinel, so that one can collect a list of resources +to perform policy checks on without having to write complex module or +configuration traversal. As an example, the following code will return all +`aws_instance` resource types within the configuration, regardless of what +module they are in: + + all_aws_instances = filter tfconfig.resources as _, r { + r.mode is "managed" and + r.type is "aws_instance" + } + +You can add specific attributes to the filter to narrow the search, such as the +module address. The following code would return resources in a module named +`foo` only: + + all_aws_instances = filter tfconfig.resources as _, r { + r.module_address is "module.foo" and + r.mode is "managed" and + r.type is "aws_instance" + } + +### Address Differences Between `tfconfig`, `tfplan`, and `tfstate` + +This import deals with configuration before it is expanded into a +resource graph by Terraform. As such, it is not possible to compute an index as +the import is building its collections and computing addresses for resources and +modules. + +As such, addresses found here may not always match the expanded addresses found +in the [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) and [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) +imports, specifically when +[`count`](/terraform/language/resources#count-multiple-resource-instances-by-count) +and +[`for_each`](/terraform/language/resources#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings), +are used. + +As an example, consider a resource named `null_resource.foo` with a count of `2` +located in a module named `bar`. While there will possibly be entries in the +other imports for `module.bar.null_resource.foo[0]` and +`module.bar.null_resource.foo[1]`, in `tfconfig/v2`, there will only be a +`module.bar.null_resource.foo`. As mentioned in the start of this section, this +is because configuration actually _defines_ this scaling, whereas _expansion_ +actually happens when the resource graph is built, which happens as a natural +part of the refresh and planning process. + +The `strip_index` helper function, found in this import, can assist in +removing the indexes from addresses found in the `tfplan/v2` and `tfstate/v2` +imports so that data from those imports can be used to reference data in this +one. + +## The `strip_index` Function + +The `strip_index` helper function can be used to remove indexes from addresses +found in [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) and [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2), +by removing the indexes from each resource. + +This can be used to help facilitate cross-import lookups for data between plan, +state, and config. + + import "tfconfig/v2" as tfconfig + import "tfplan/v2" as tfplan + + main = rule { + all filter tfplan.resource_changes as _, rc { + rc.mode is "managed" and + rc.type is "aws_instance" + } as _, rc { + tfconfig.resources[tfconfig.strip_index(rc.address)].config.ami.constant_value is "ami-abcdefgh012345" + } + } + +## Expression Representations + +Most collections in this import will have one of two kinds of _expression +representations_. This is a verbose format for expressing a (parsed) +configuration value independent of the configuration source code, which is not +100% available to a policy check in HCP Terraform. + + (expression representation) + ├── constant_value (value) + └── references (list of strings) + +There are two major parts to an expression representation: + +- Any _strictly constant value_ is expressed as an expression with a + `constant_value` field. +- Any expression that requires some degree of evaluation to generate the final + value - even if that value is known at plan time - is not expressed in + configuration. Instead, any particular references that are made are added to + the `references` field. More details on this field can be found in the + [expression + representation](/terraform/internals/json-format#expression-representation) + section of the JSON output format documentation. + +For example, to determine if an output is based on a particular +resource value, one could do: + + import "tfconfig/v2" as tfconfig + + main = rule { + tfconfig.outputs["instance_id"].value.references is ["aws_instance.foo"] + } + +-> **Note:** The representation does not account for +complex interpolations or other expressions that combine constants with other +expression data. For example, the partially constant data in `"foo${var.bar}"` would be lost. + +### Block Expression Representation + +Expanding on the above, a multi-value expression representation (such as the +kind found in a [`resources`](#the-resources-collection) collection element) is +similar, but the root value is a keyed map of expression representations. This +is repeated until a "scalar" expression value is encountered, ie: a field that +is not a block in the resource's schema. + + (block expression representation) + └── (attribute key) + ├── (child block expression representation) + │ └── (...) + ├── constant_value (value) + └── references (list of strings) + +As an example, one can validate expressions in an +[`aws_instance`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance) resource using the +following: + + import "tfconfig/v2" as tfconfig + + main = rule { + tfconfig.resources["aws_instance.foo"].config.ami.constant_value is "ami-abcdefgh012345" + } + +Note that _nested blocks_, sometimes known as _sub-resources_, will be nested in +configuration as a list of blocks (reflecting their ultimate nature as a list +of objects). An example would be the `aws_instance` resource's +[`ebs_block_device`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance#ebs-ephemeral-and-root-block-devices) block: + + import "tfconfig/v2" as tfconfig + + main = rule { + tfconfig.resources["aws_instance.foo"].config.ebs_block_device[0].volume_size < 10 + } + +## The `providers` Collection + +The `providers` collection is a collection representing the configurations of +all provider instances across all modules in the configuration. + +This collection is indexed by an opaque key. This is currently +`module_address:provider.alias`, the same value as found in the +`provider_config_key` field. `module_address` and the colon delimiter are +omitted for the root module. + +The `provider_config_key` field is also found in the `resources` collection and +can be used to locate a provider that belongs to a configured resource. + +The fields in this collection are as follows: + +- `provider_config_key` - The opaque configuration key, used as the index key. +- `name` - The name of the provider, ie: `aws`. +- `full_name` - The fully-qualified name of the provider, e.g. `registry.terraform.io/hashicorp/aws`. +- `alias` - The alias of the provider, ie: `east`. Empty for a default provider. +- `module_address` - The address of the module this provider appears in. +- `config` - A [block expression + representation](#block-expression-representation) with provider configuration + values. +- `version_constraint` - The defined version constraint for this provider. + +## The `resources` Collection + +The `resources` collection is a collection representing all of the resources +found in all modules in the configuration. + +This collection is indexed by the resource address. + +The fields in this collection are as follows: + +- `address` - The resource address. This is the index of the collection. +- `module_address` - The module address that this resource was found in. +- `mode` - The resource mode, either `managed` (resources) or `data` (data + sources). +- `type` - The type of resource, ie: `null_resource` in `null_resource.foo`. +- `name` - The name of the resource, ie: `foo` in `null_resource.foo`. +- `provider_config_key` - The opaque configuration key that serves as the index + of the [`providers`](#the-providers-collection) collection. +- `provisioners` - The ordered list of provisioners for this resource. The + syntax of the provisioners matches those found in the + [`provisioners`](#the-provisioners-collection) collection, but is a list + indexed by the order the provisioners show up in the resource. +- `config` - The [block expression + representation](#block-expression-representation) of the configuration values + found in the resource. +- `count` - The [expression data](#expression-representations) for the `count` + value in the resource. +- `for_each` - The [expression data](#expression-representations) for the + `for_each` value in the resource. +- `depends_on` - The contents of the `depends_on` config directive, which + declares explicit dependencies for this resource. + +## The `provisioners` Collection + +The `provisioners` collection is a collection of all of the provisioners found +across all resources in the configuration. + +While normally bound to a resource in an ordered fashion, this collection allows +for the filtering of provisioners within a single expression. + +This collection is indexed with a key following the format +`resource_address:index`, with each field matching their respective field in the +particular element below: + +- `resource_address`: The address of the resource that the provisioner was found + in. This can be found in the [`resources`](#the-resources-collection) + collection. +- `type`: The provisioner type, ie: `local_exec`. +- `index`: The provisioner index as it shows up in the resource provisioner + order. +- `config`: The [block expression + representation](#block-expression-representation) of the configuration values + in the provisioner. + +## The `variables` Collection + +The `variables` collection is a collection of all variables across all modules +in the configuration. + +Note that this tracks variable definitions, not values. See the [`tfplan/v2` +`variables` collection](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-variables-collection) for variable +values set within a plan. + +This collection is indexed by the key format `module_address:name`, with each +field matching their respective name below. `module_address` and the colon +delimiter are omitted for the root module. + +- `module_address` - The address of the module the variable was found in. +- `name` - The name of the variable. +- `default` - The defined default value of the variable. +- `description` - The description of the variable. + +## The `outputs` Collection + +The `outputs` collection is a collection of all outputs across all modules in +the configuration. + +Note that this tracks variable definitions, not values. See the [`tfstate/v2` +`outputs` collection](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2#the-outputs-collection) for the final +values of outputs set within a state. The [`tfplan/v2` `output_changes` +collection](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-output_changes-collection) also contains a more +complex collection of planned output changes. + +This collection is indexed by the key format `module_address:name`, with each +field matching their respective name below. `module_address` and the colon +delimiter are omitted for the root module. + +- `module_address` - The address of the module the output was found in. +- `name` - The name of the output. +- `sensitive` - Indicates whether or not the output was marked as + [`sensitive`](/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output). +- `value` - An [expression representation](#expression-representations) for the output. +- `description` - The description of the output. +- `depends_on` - A list of resource names that the output depends on. These are + the hard-defined output dependencies as defined in the + [`depends_on`](/terraform/language/values/outputs#depends_on-explicit-output-dependencies) + field in an output declaration, not the dependencies that get derived from + natural evaluation of the output expression (these can be found in the + `references` field of the expression representation). + +## The `module_calls` Collection + +The `module_calls` collection is a collection of all module declarations at all +levels within the configuration. + +Note that this is the +[`module`](/terraform/language/modules#calling-a-child-module) stanza in +any particular configuration, and not the module itself. Hence, a declaration +for `module.foo` would actually be declared in the root module, which would be +represented by a blank field in `module_address`. + +This collection is indexed by the key format `module_address:name`, with each +field matching their respective name below. `module_address` and the colon +delimiter are omitted for the root module. + +- `module_address` - The address of the module the declaration was found in. +- `name` - The name of the module. +- `source` - The contents of the `source` field. +- `config` - A [block expression + representation](#block-expression-representation) for all parameter values + sent to the module. +- `count` - An [expression representation](#expression-representations) for the + `count` field. +- `depends_on`: An [expression representation](#expression-representations) for the + `depends_on` field. +- `for_each` - An [expression representation](#expression-representations) for + the `for_each` field. +- `version_constraint` - The string value found in the `version` field of the + module declaration. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfconfig.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfconfig.mdx new file mode 100644 index 0000000000..dd83787db5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfconfig.mdx @@ -0,0 +1,976 @@ +--- +page_title: tfconfig Sentinel import +description: Use tfconfig import to give Sentinel access to a Terraform configuration. +source: terraform-docs-common +--- + +# tfconfig Sentinel import + +~> **Warning:** The `tfconfig` import is now deprecated and will be permanently removed in August 2025. We recommend that you start using the updated [tfconfig/v2](/terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2) import as soon as possible to avoid disruptions. The `tfconfig/v2` import offers improved functionality and is designed to better support your policy enforcement needs. + +The `tfconfig` import provides access to a Terraform configuration. + +The Terraform configuration is the set of `*.tf` files that are used to +describe the desired infrastructure state. Policies using the `tfconfig` +import can access all aspects of the configuration: providers, resources, +data sources, modules, and variables. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Some use cases for `tfconfig` include: + +- **Organizational naming conventions**: requiring that configuration elements + are named in a way that conforms to some organization-wide standard. +- **Required inputs and outputs**: organizations may require a particular set + of input variable names across all workspaces or may require a particular + set of outputs for asset management purposes. +- **Enforcing particular modules**: organizations may provide a number of + "building block" modules and require that each workspace be built only from + combinations of these modules. +- **Enforcing particular providers or resources**: an organization may wish to + require or prevent the use of providers and/or resources so that configuration + authors cannot use alternative approaches to work around policy + restrictions. + +Note with these use cases that this import is concerned with object _names_ +in the configuration. Since this is the configuration and not an invocation +of Terraform, you can't see values for variables, the state, or the diff for +a pending plan. If you want to write policy around expressions used +within configuration blocks, you likely want to use the +[`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import. + +## Namespace Overview + +The following is a tree view of the import namespace. For more detail on a +particular part of the namespace, see below. + +-> **Note:** The root-level alias keys shown here (`data`, `modules`, +`providers`, `resources`, and `variables`) are shortcuts to a [module +namespace](#namespace-module) scoped to the root module. For more details, see +the section on [root namespace aliases](#root-namespace-aliases). + + tfconfig + ├── module() (function) + │ └── (module namespace) + │ ├── data + │ │ └── TYPE.NAME + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── provisioners + │ │ └── NUMBER + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── type (string) + │ ├── modules + │ │ └── NAME + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ ├── source (string) + │ │ └── version (string) + │ ├──outputs + │ │ └── NAME + │ │ ├── depends_on (list of strings) + │ │ ├── description (string) + │ │ ├── sensitive (boolean) + │ │ ├── references (list of strings) (TF 0.12 and later) + │ │ └── value (value) + │ ├── providers + │ │ └── TYPE + │ │ ├── alias + │ │ │ └── ALIAS + │ │ │ ├── config (map of keys) + │ │ | ├── references (map of keys) (TF 0.12 and later) + │ │ │ └── version (string) + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── version (string) + │ ├── resources + │ │ └── TYPE.NAME + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── provisioners + │ │ └── NUMBER + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── type (string) + │ └── variables + │ └── NAME + │ ├── default (value) + │ └── description (string) + ├── module_paths ([][]string) + │ + ├── data (root module alias) + ├── modules (root module alias) + ├── outputs (root module alias) + ├── providers (root module alias) + ├── resources (root module alias) + └── variables (root module alias) + +### `references` with Terraform 0.12 + +**With Terraform 0.11 or earlier**, if a configuration value is defined as an +expression (and not a static value), the value will be accessible in its raw, +non-interpolated string (just as with a constant value). + +As an example, consider the following resource block: + +```hcl +resource "local_file" "accounts" { + content = "some text" + filename = "${var.subdomain}.${var.domain}/accounts.txt" +} +``` + +In this example, one might want to ensure `domain` and `subdomain` input +variables are used within `filename` in this configuration. With Terraform 0.11 or +earlier, the following policy would evaluate to `true`: + +```python +import "tfconfig" + +# filename_value is the raw, non-interpolated string +filename_value = tfconfig.resources.local_file.accounts.config.filename + +main = rule { + filename_value contains "${var.domain}" and + filename_value contains "${var.subdomain}" +} +``` + +**With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present within the +configuration value and `references` should be used instead: + +```python +import "tfconfig" + +# filename_references is a list of string values containing the references used in the expression +filename_references = tfconfig.resources.local_file.accounts.references.filename + +main = rule { + filename_references contains "var.domain" and + filename_references contains "var.subdomain" +} +``` + +The `references` value is present in any namespace where non-constant +configuration values can be expressed. This is essentially every namespace +which has a `config` value as well as the `outputs` namespace. + +-> **Note:** Remember, this import enforces policy around the literal Terraform +configuration and not the final values as a result of invoking Terraform. If +you want to write policy around the _result_ of expressions used within +configuration blocks (for example, if you wanted to ensure the final value of +`filename` above includes `accounts.txt`), you likely want to use the +[`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import. + +## Namespace: Root + +The root-level namespace consists of the values and functions documented below. + +In addition to this, the root-level `data`, `modules`, `providers`, `resources`, +and `variables` keys all alias to their corresponding namespaces within the +[module namespace](#namespace-module). + + + +### Function: `module()` + + module = func(ADDR) + +- **Return Type:** A [module namespace](#namespace-module). + +The `module()` function in the [root namespace](#namespace-root) returns the +[module namespace](#namespace-module) for a particular module address. + +The address must be a list and is the module address, split on the period (`.`), +excluding the root module. + +Hence, a module with an address of simply `foo` (or `root.foo`) would be +`["foo"]`, and a module within that (so address `foo.bar`) would be read as +`["foo", "bar"]`. + +[`null`][ref-null] is returned if a module address is invalid, or if the module +is not present in the configuration. + +[ref-null]: /sentinel/docs/language/spec#null + +As an example, given the following module block: + +```hcl +module "foo" { + # ... +} +``` + +If the module contained the following content: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { subject.module(["foo"]).resources.null_resource.foo.config.triggers[0].foo is "bar" } +``` + + + +### Value: `module_paths` + +- **Value Type:** List of a list of strings. + +The `module_paths` value within the [root namespace](#namespace-root) is a list +of all of the modules within the Terraform configuration. + +Modules not present in the configuration will not be present here, even if they +are present in the diff or state. + +This data is represented as a list of a list of strings, with the inner list +being the module address, split on the period (`.`). + +The root module is included in this list, represented as an empty inner list. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The value of `module_paths` would be: + + [ + [], + ["foo"], + ] + +And the following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.module_paths contains ["foo"] } +``` + +#### Iterating Through Modules + +Iterating through all modules to find particular resources can be useful. This +[example][iterate-over-modules] shows how to use `module_paths` with the +[`module()` function](#function-module-) to find all resources of a +particular type from all modules using the `tfplan` import. By changing `tfplan` +in this function to `tfconfig`, you could make a similar function find all +resources of a specific type in the Terraform configuration. + +[iterate-over-modules]: /terraform/enterprise/policy-enforcement/sentinel#sentinel-imports + +## Namespace: Module + +The **module namespace** can be loaded by calling [`module()`](#root-function-module) +for a particular module. + +It can be used to load the following child namespaces: + +- `data` - Loads the [resource namespace](#namespace-resources-data-sources), + filtered against data sources. +- `modules` - Loads the [module configuration + namespace](#namespace-module-configuration). +- `outputs` - Loads the [output namespace](#namespace-outputs). +- `providers` - Loads the [provider namespace](#namespace-providers). +- `resources` - Loads the [resource + namespace](#namespace-resources-data-sources), filtered against resources. +- `variables` - Loads the [variable namespace](#namespace-variables). + +### Root Namespace Aliases + +The root-level `data`, `modules`, `providers`, `resources`, and `variables` keys +all alias to their corresponding namespaces within the module namespace, loaded +for the root module. They are the equivalent of running `module([]).KEY`. + + + +## Namespace: Resources/Data Sources + +The **resource namespace** is a namespace _type_ that applies to both resources +(accessed by using the `resources` namespace key) and data sources (accessed +using the `data` namespace key). + +Accessing an individual resource or data source within each respective namespace +can be accomplished by specifying the type and name, in the syntax +`[resources|data].TYPE.NAME`. + +In addition, each of these namespace levels is a map, allowing you to filter +based on type and name. Some examples of multi-level access are below: + +- To fetch all `aws_instance` resources within the root module, you can specify + `tfconfig.resources.aws_instance`. This would give you a map of resource + namespaces indexed from the names of each resource (`foo`, `bar`, and so + on). +- To fetch all resources within the root module, irrespective of type, use + `tfconfig.resources`. This is indexed by type, as shown above with + `tfconfig.resources.aws_instance`, with names being the next level down. + +As an example, perhaps you wish to deny use of the `local_file` resource +in your configuration. Consider the following resource block: + +```hcl +resource "local_file" "foo" { + content = "foo!" + filename = "${path.module}/foo.bar" +} +``` + +The following policy would fail: + +```python +import "tfconfig" + +main = rule { tfconfig.resources not contains "local_file" } +``` + +Further explanation of the namespace will be in the context of resources. As +mentioned, when operating on data sources, use the same syntax, except with +`data` in place of `resources`. + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +The `config` value within the [resource +namespace](#namespace-resources-data-sources) is a map of key-value pairs that +directly map to Terraform config keys and values. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#resources-value-references) should be used instead. + +As an example, consider the following resource block: + +```hcl +resource "local_file" "accounts" { + content = "some text" + filename = "accounts.txt" +} +``` + +In this example, one might want to access `filename` to validate that the correct +file name is used. Given the above example, the following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { + tfconfig.resources.local_file.accounts.config.filename is "accounts.txt" +} +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [resource namespace](#namespace-resources-data-sources) +contains the identifiers within non-constant expressions found in [`config`](#resources-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + + + +### Value: `provisioners` + +- **Value Type:** List of [provisioner namespaces](#namespace-provisioners). + +The `provisioners` value within the [resource namespace](#namespace-resources) +represents the [provisioners][ref-tf-provisioners] within a specific resource. + +Provisioners are listed in the order they were provided in the configuration +file. + +While the `provisioners` value will be present within data sources, it will +always be an empty map (in Terraform 0.11) or `null` (in Terraform 0.12) since +data sources cannot actually have provisioners. + +The data within a provisioner can be inspected via the returned [provisioner +namespace](#namespace-provisioners). + +[ref-tf-provisioners]: /terraform/language/resources/provisioners/syntax + +## Namespace: Provisioners + +The **provisioner namespace** represents the configuration for a particular +[provisioner][ref-tf-provisioners] within a specific resource. + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +The `config` value within the [provisioner namespace](#namespace-provisioners) +represents the values of the keys within the provisioner. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#provisioners-value-references) should be used instead. + +As an example, given the following resource block: + +```hcl +resource "null_resource" "foo" { + # ... + + provisioner "local-exec" { + command = "echo ${self.private_ip} > file.txt" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { + tfconfig.resources.null_resource.foo.provisioners[0].config.command is "echo ${self.private_ip} > file.txt" +} +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [provisioner namespace](#namespace-provisioners) +contains the identifiers within non-constant expressions found in [`config`](#provisioners-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + + + +### Value: `type` + +- **Value Type:** String. + +The `type` value within the [provisioner namespace](#namespace-provisioners) +represents the type of the specific provisioner. + +As an example, in the following resource block: + +```hcl +resource "null_resource" "foo" { + # ... + + provisioner "local-exec" { + command = "echo ${self.private_ip} > file.txt" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.resources.null_resource.foo.provisioners[0].type is "local-exec" } +``` + +## Namespace: Module Configuration + +The **module configuration** namespace displays data on _module configuration_ +as it is given within a `module` block. This means that the namespace concerns +itself with the contents of the declaration block (example: the `source` +parameter and variable assignment keys), not the data within the module +(example: any contained resources or data sources). For the latter, the module +instance would need to be looked up with the [`module()` +function](#root-function-module). + + + +### Value: `source` + +- **Value Type:** String. + +The `source` value within the [module configuration +namespace](#namespace-module-configuration) represents the module source path as +supplied to the module configuration. + +As an example, given the module declaration block: + +```hcl +module "foo" { + source = "./foo" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.modules.foo.source is "./foo" } +``` + + + +### Value: `version` + +- **Value Type:** String. + +The `version` value within the [module configuration +namespace](#namespace-module-configuration) represents the [version +constraint][module-version-constraint] for modules that support it, such as +modules within the [Terraform Module Registry][terraform-module-registry] or the +[HCP Terraform private module registry][tfe-private-registry]. + +[module-version-constraint]: /terraform/language/modules#module-versions + +[terraform-module-registry]: https://registry.terraform.io/ + +[tfe-private-registry]: /terraform/enterprise/registry + +As an example, given the module declaration block: + +```hcl +module "foo" { + source = "foo/bar" + version = "~> 1.2" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.modules.foo.version is "~> 1.2" } +``` + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#modules-value-references) should be used instead. + +The `config` value within the [module configuration +namespace](#namespace-module-configuration) represents the values of the keys +within the module configuration. This is every key within a module declaration +block except [`source`](#modules-value-source) and [`version`](#modules-value-version), which +have their own values. + +As an example, given the module declaration block: + +```hcl +module "foo" { + source = "./foo" + + bar = "baz" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.modules.foo.config.bar is "baz" } +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [module configuration namespace](#namespace-module-configuration) +contains the identifiers within non-constant expressions found in [`config`](#modules-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + +## Namespace: Outputs + +The **output namespace** represents _declared_ output data within a +configuration. As such, configuration for the [`value`](#outputs-value-value) attribute +will be in its raw form, and not yet interpolated. For fully interpolated output +values, see the [`tfstate` import][ref-tfe-sentinel-tfstate]. + +[ref-tfe-sentinel-tfstate]: /terraform/enterprise/policy-enforcement/import-reference/tfstate-v2 + +This namespace is indexed by output name. + + + +### Value: `depends_on` + +- **Value Type:** A list of strings. + +The `depends_on` value within the [output namespace](#namespace-outputs) +represents any _explicit_ dependencies for this output. For more information, +see the [depends_on output setting][ref-depends_on] within the general Terraform +documentation. + +[ref-depends_on]: /terraform/language/values/outputs#depends_on + +As an example, given the following output declaration block: + +```hcl +output "id" { + depends_on = ["null_resource.bar"] + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.depends_on[0] is "null_resource.bar" } +``` + + + +### Value: `description` + +- **Value Type:** String. + +The `description` value within the [output namespace](#namespace-outputs) +represents the defined description for this output. + +As an example, given the following output declaration block: + +```hcl +output "id" { + description = "foobar" + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.description is "foobar" } +``` + + + +### Value: `sensitive` + +- **Value Type:** Boolean. + +The `sensitive` value within the [output namespace](#namespace-outputs) +represents if this value has been marked as sensitive or not. + +As an example, given the following output declaration block: + +```hcl +output "id" { + sensitive = true + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { subject.outputs.id.sensitive } +``` + + + +### Value: `value` + +- **Value Type:** Any primitive type, list or map. + +The `value` value within the [output namespace](#namespace-outputs) represents +the defined value for the output as declared in the configuration. Primitives +will bear the implicit type of their declaration (string, int, float, or bool), +and maps and lists will be represented as such. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#outputs-value-references) should be used instead. + +As an example, given the following output declaration block: + +```hcl +output "id" { + value = "${null_resource.foo.id}" +} +``` + +With Terraform 0.11 or earlier the following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.value is "${null_resource.foo.id}" } +``` + + + +### Value: `references` + +- **Value Type:**. List of strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [output namespace](#namespace-outputs) +contains the names of any referenced identifiers when [`value`](#outputs-value-value) +is a non-constant expression. + +As an example, given the following output declaration block: + +```hcl +output "id" { + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.references contains "null_resource.foo.id" } +``` + +## Namespace: Providers + +The **provider namespace** represents data on the declared providers within a +namespace. + +This namespace is indexed by provider type and _only_ contains data about +providers when actually declared. If you are using a completely implicit +provider configuration, this namespace will be empty. + +This namespace is populated based on the following criteria: + +- The top-level namespace [`config`](#providers-value-config) and + [`version`](#providers-value-version) values are populated with the configuration and + version information from the default provider (the provider declaration that + lacks an alias). +- Any aliased providers are added as namespaces within the + [`alias`](#providers-value-alias) value. +- If a module lacks a default provider configuration, the top-level `config` and + `version` values will be empty. + + + +### Value: `alias` + +- **Value Type:** A map of [provider namespaces](#namespace-providers), indexed + by alias. + +The `alias` value within the [provider namespace](#namespace-providers) +represents all declared [non-default provider +instances][ref-tf-provider-instances] for a specific provider type, indexed by +their specific alias. + +[ref-tf-provider-instances]: /terraform/language/providers/configuration#alias-multiple-provider-configurations + +The return type is a provider namespace with the data for the instance in +question loaded. The `alias` key will not be available within this namespace. + +As an example, given the following provider declaration block: + +```hcl +provider "aws" { + alias = "east" + region = "us-east-1" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.providers.aws.alias.east.config.region is "us-east-1" } +``` + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#providers-value-references) should be used instead. + +The `config` value within the [provider namespace](#namespace-providers) +represents the values of the keys within the provider's configuration, with the +exception of the provider version, which is represented by the +[`version`](#providers-value-version) value. [`alias`](#providers-value-alias) is also not included +when the provider is aliased. + +As an example, given the following provider declaration block: + +```hcl +provider "aws" { + region = "us-east-1" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.providers.aws.config.region is "us-east-1" } +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [provider namespace](#namespace-providers) +contains the identifiers within non-constant expressions found in [`config`](#providers-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + + + +### Value: `version` + +- **Value Type:** String. + +The `version` value within the [provider namespace](#namespace-providers) +represents the explicit expected version of the supplied provider. This includes +the pessimistic operator. + +As an example, given the following provider declaration block: + +```hcl +provider "aws" { + version = "~> 1.34" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.providers.aws.version is "~> 1.34" } +``` + +## Namespace: Variables + +The **variable namespace** represents _declared_ variable data within a +configuration. As such, static data can be extracted, such as defaults, but not +dynamic data, such as the current value of a variable within a plan (although +this can be extracted within the [`tfplan` import][ref-tfe-sentinel-tfplan]). + +[ref-tfe-sentinel-tfplan]: /terraform/enterprise/policy-enforcement/import-reference/tfplan-v2 + +This namespace is indexed by variable name. + + + +### Value: `default` + +- **Value Type:** Any primitive type, list, map, or `null`. + +The `default` value within the [variable namespace](#namespace-variables) +represents the default for the variable as declared in the configuration. + +The actual value will be as configured. Primitives will bear the implicit type +of their declaration (string, int, float, or bool), and maps and lists will be +represented as such. + +If no default is present, the value will be [`null`][ref-sentinel-null] (not to +be confused with [`undefined`][ref-sentinel-undefined]). + +[ref-sentinel-null]: /sentinel/docs/language/spec#null + +[ref-sentinel-undefined]: /sentinel/docs/language/undefined + +As an example, given the following variable blocks: + +```hcl +variable "foo" { + default = "bar" +} + +variable "number" { + default = 42 +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +default_foo = rule { tfconfig.variables.foo.default is "bar" } +default_number = rule { tfconfig.variables.number.default is 42 } + +main = rule { default_foo and default_number } +``` + + + +### Value: `description` + +- **Value Type:** String. + +The `description` value within the [variable namespace](#namespace-variables) +represents the description of the variable, as provided in configuration. + +As an example, given the following variable block: + +```hcl +variable "foo" { + description = "foobar" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.variables.foo.description is "foobar" } +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfplan-v2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfplan-v2.mdx new file mode 100644 index 0000000000..68d18aa3dd --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfplan-v2.mdx @@ -0,0 +1,388 @@ +--- +page_title: tfplan/v2 Sentinel import +description: Use tfplan/v2 import to give Sentinel access to a Terraform plan. +source: terraform-docs-common +--- + +-> **Note:** This is documentation for the next version of the `tfplan` Sentinel +import, designed specifically for Terraform 0.12. This import requires +Terraform 0.12 or higher, and must currently be loaded by path, using an alias, +example: `import "tfplan/v2" as tfplan`. + +# tfplan/v2 Sentinel import + +The `tfplan/v2` import provides access to a Terraform plan. + +A Terraform plan is the file created as a result of `terraform plan` and is the +input to `terraform apply`. The plan represents the changes that Terraform needs +to make to infrastructure to reach the desired state represented by the +configuration. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +In addition to the diff data available in the plan, there is a "planned state" +that is available through this import, via the +[`planned_values`](#the-planned_values-collection) collection. This collection +presents the Terraform state as how it might look after the plan data is +applied, but is not guaranteed to be the final state. + +The data in the `tfplan/v2` import is sourced from the JSON configuration file +that is generated by the [`terraform show -json`](/terraform/cli/commands/show#json-output) command. For more information on +the file format, see the [JSON Output Format](/terraform/internals/json-format) +page. + +The entirety of the JSON output file is exposed as a Sentinel map via the +[`raw`](#the-raw-collection) collection. This allows direct, low-level access to +the JSON data, but should only be used in complex situations where the +higher-level collections do not serve the purpose. + +## Import Overview + +The `tfplan/v2` import is structured as a series of _collections_, keyed as a +specific format depending on the collection. + + tfplan/v2 + ├── terraform_version (string) + ├── variables + │ └── (indexed by name) + │ ├── name (string) + │ └── value (value) + ├── planned_values + │ ├── outputs (tfstate/v2 outputs representation) + │ └── resources (tfstate/v2 resources representation) + ├── resource_changes + │ └── (indexed by address[:deposed]) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── index (float (number) or string) + │ ├── provider_name (string) + │ ├── deposed (string) + │ └── change (change representation) + ├── resource_drift + │ └── (indexed by address[:deposed]) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── index (float (number) or string) + │ ├── provider_name (string) + │ ├── deposed (string) + │ └── change (change representation) + ├── output_changes + │ └── (indexed by name) + │ ├── name (string) + │ └── change (change representation) + └── raw (map) + +The collections are: + +- [`variables`](#the-variables-collection) - The values of variables that have + been set in the plan itself. This collection only contains variables set in + the root module. +- [`planned_values`](#the-planned_values-collection) - The state representation + of _planned values_, or an estimation of what the state will look like after + the plan is applied. +- [`resource_changes`](#the-resource_changes-and-resource_drift-collections) - The set of change + operations for resources and data sources within this plan. +- [`resource_drift`](#the-resource_changes-and-resource_drift-collections) - A description of the + changes Terraform detected when it compared the most recent state to the prior saved state. +- [`output_changes`](#the-output_changes-collection) - The changes to outputs + within this plan. This collection only contains outputs set in the root + module. +- [`raw`](#the-raw-collection) - Access to the raw plan data as stored by + HCP Terraform. + +These collections are specifically designed to be used with the +[`filter`](/sentinel/docs/language/collection-operations#filter-expression) +quantifier expression in Sentinel, so that one can collect a list of resources +to perform policy checks on without having to write complex discovery code. As +an example, the following code will return all `aws_instance` resource changes, +across all modules in the plan: + + all_aws_instances = filter tfplan.resource_changes as _, rc { + rc.mode is "managed" and + rc.type is "aws_instance" + } + +You can add specific attributes to the filter to narrow the search, such as the +module address, or the operation being performed. The following code would +return resources in a module named `foo` only, and further narrow the search +down to only resources that were being created: + + all_aws_instances = filter tfplan.resource_changes as _, rc { + rc.module_address is "module.foo" and + rc.mode is "managed" and + rc.type is "aws_instance" and + rc.change.actions is ["create"] + } + +### Change Representation + +Certain collections in this import contain a _change representation_, an object +with details about changes to a particular entity, such as a resource (within +the [`resource_changes`](#the-resource_changes-collection) collection), or +output (within the [`output_changes`](#the-output_changes-collection) +collection). + + (change representation) + ├── actions (list) + ├── before (value, or map) + ├── after (value, or map) + └── after_unknown (boolean, or map of booleans) + +This change representation contains the following fields: + +- `actions` - A list of actions being carried out for this change. The order is + important, for example a regular replace operation is denoted by `["delete", + "create"]`, but a + [`create_before_destroy`](/terraform/language/meta-arguments/lifecycle#create_before_destroy) + resource will have an operation order of `["create", "delete"]`. +- `before` - The representation of the resource data object value before the + action. For create-only actions, this is unset. For no-op actions, this value + will be identical with `after`. +- `after` - The representation of the resource data object value after the + action. For delete-only actions, this is unset. For no-op actions, this value + will be identical with `before`. Note that unknown values will not show up in + this field. +- `after_unknown` - A deep object of booleans that denotes any values that are + unknown in a resource. These values were previously referred to as "computed" + values. If the value cannot be found in this map, then its value should be + available within `after`, so long as the operation supports it. + +#### Actions + +As mentioned above, actions show up within the `actions` field of a change +representation and indicate the type of actions being performed as part of the +change, and the order that they are being performed in. + +The current list of actions are as follows: + +- `create` - The action will create the associated entity. Depending on the + order this appears in, the entity may be created alongside a copy of the + entity before replacing it. +- `read` - The action will read the associated entity. In practice, seeing this + change type should be rare, as reads generally happen before a plan is + executed (usually during a refresh). +- `update` - The action will update the associated entity in a way that alters its state + in some way. +- `delete` - The action will remove the associated entity, deleting any + applicable state and associated real resources or infrastructure. +- `no-op` - No action will be performed on the associated entity. + +The `actions` field is a list, as some real-world actions are actually a +composite of more than one primitive action. At this point in time, this +is generally only applicable to resource replacement, in which the following +action orders apply: + +- **Normal replacement:** `["delete", "create"]` - Applies to default lifecycle + configurations. +- **Create-before-destroy:** `["create", "delete"]` - Applies when + [`create_before_destroy`](/terraform/language/meta-arguments/lifecycle#create_before_destroy) + is used in a lifecycle configuration. + +Note that, in most situations, the plan will list all "changes", including no-op +changes. This makes filtering on change type crucial to the accurate selection +of data if you are concerned with the state change of a particular resource. + +To filter on a change type, use exact list comparison. For example, the +following example from the [Import Overview](#import-overview) filters on +exactly the resources being created _only_: + + all_aws_instances = filter tfplan.resource_changes as _, rc { + rc.module_address is "module.foo" and + rc.mode is "managed" and + rc.type is "aws_instance" and + rc.change.actions is ["create"] + } + +#### `before`, `after`, and `after_unknown` + +The exact attribute changes for a particular operation are outlined in the +`before` and `after` attributes. Depending on the entity being operated on, this +will either be a map (as with +[`resource_changes`](#the-resource_changes-collection)) or a singular value (as +with [`output_changes`](#the-output_changes-collection)). + +What you can expect in these fields varies depending on the operation: + +- For fresh create operations, `before` will generally be `null`, and `after` + will contain the data you can expect to see after the change. +- For full delete operations, this will be reversed - `before` will contain + data, and `after` will be `null`. +- Update or replace operations will have data in both fields relevant to their + states before and after the operation. +- No-op operations should have identical data in `before` and `after`. + +For resources, if a field cannot be found in `after`, it generally means one of +two things: + +- The attribute does not exist in the resource schema. Generally, known + attributes that do not have a value will show up as `null` or otherwise empty + in `after`. +- The attribute is _unknown_, that is, it was unable to be determined at plan + time and will only be available after apply-time values have been able to be + calculated. + +In the latter case, there should be a value for the particular attribute in +`after_unknown`, which can be checked to assert that the value is indeed +unknown, versus invalid: + + import "tfplan/v2" as tfplan + + no_unknown_amis = rule { + all filter tfplan.resource_changes as _, rc { + rc.module_address is "module.foo" and + rc.mode is "managed" and + rc.type is "aws_instance" and + rc.change.actions is ["create"] + } as _, rc { + rc.change.after_unknown.ami else false is false + } + } + +For output changes, `after_unknown` will simply be `true` if the value won't be +known until the plan is applied. + +## The `terraform_version` Value + +The top-level `terraform_version` value in this import gives the Terraform +version that made the plan. This can be used to do version validation. + + import "tfplan/v2" as tfplan + import "strings" + + v = strings.split(tfplan.terraform_version, ".") + version_major = int(v[1]) + version_minor = int(v[2]) + + main = rule { + version_major is 12 and version_minor >= 19 + } + +-> **NOTE:** The above example will give errors when working with pre-release +versions (example: `0.12.0beta1`). Future versions of this import will include +helpers to assist with processing versions that will account for these kinds of +exceptions. + +## The `variables` Collection + +The `variables` collection is a collection of the variables set in the root +module when creating the plan. + +This collection is indexed on the name of the variable. + +The valid values are: + +- `name` - The name of the variable, also used as the collection key. +- `value` - The value of the variable assigned during the plan. + +## The `planned_values` Collection + +The `planned_values` collection is a special collection in that it contains two +fields that alias to state collections with the _planned_ state set. This is the +best prediction of what the state will look like after the plan is executed. + +The two fields are: + +- `outputs` - The prediction of what output values will look like after the + state is applied. For more details on the structure of this collection, see + the [`outputs`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2#the-outputs-collection) collection in the + [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) documentation. +- `resources` - The prediction of what resource values will look like after the + state is applied. For more details on the structure of this collection, see + the [`resources`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2#the-resources-collection) collection in the + [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) documentation. + +-> **NOTE:** Unknown values are omitted from the `planned_values` state +representations, regardless of whether or not they existed before. Use +[`resource_changes`](#the-resource_changes-collection) if awareness of unknown +data is important. + +## The `resource_changes` and `resource_drift` Collections + +The `resource_changes` and `resource_drift` collections are a set of change operations for resources +and data sources within this plan. + +The `resource_drift` collection provides a description of the changes Terraform detected +when it compared the most recent state to the prior saved state. + +The `resource_changes` collection includes all resources that have been found in the configuration and state, +regardless of whether or not they are changing. + +~> When [resource targeting](/terraform/cli/commands/plan#resource-targeting) is in effect, the `resource_changes` collection will only include the resources specified as targets for the run. This may lead to unexpected outcomes if a policy expects a resource to be present in the plan. To prohibit targeted runs altogether, ensure [`tfrun.target_addrs`](/terraform/enterprise/policy-enforcement/import-reference/tfrun#value-target_addrs) is undefined or empty. + +This collection is indexed on the complete resource address as the key. If +`deposed` is non-empty, it is appended to the end, and may look something like +`aws_instance.foo:deposed-abc123`. + +An element contains the following fields: + +- `address` - The absolute resource address - also the key for the collection's + index, if `deposed` is empty. + +- `module_address` - The module portion of the absolute resource address. + +- `mode` - The resource mode, either `managed` (resources) or `data` (data + sources). + +- `type` - The resource type, example: `aws_instance` for `aws_instance.foo`. + +- `name` - The resource name, example: `foo` for `aws_instance.foo`. + +- `index` - The resource index. Can be either a number or a string. + +- `provider_name` - The name of the provider this resource belongs to. This + allows the provider to be interpreted unambiguously in the unusual situation + where a provider offers a resource type whose name does not start with its own + name, such as the `googlebeta` provider offering `google_compute_instance`. + + -> **Note:** Starting with Terraform 0.13, the `provider_name` field contains the + _full_ source address to the provider in the Terraform Registry. Example: + `registry.terraform.io/hashicorp/null` for the null provider. + +- `deposed` - An identifier used during replacement operations, and can be used + to identify the exact resource being replaced in state. + +- `change` - The data describing the change that will be made to this resource. + For more details, see [Change Representation](#change-representation). + +## The `output_changes` Collection + +The `output_changes` collection is a collection of the change operations for +outputs within this plan. + +Only outputs for the root module are included. + +This collection is indexed by the name of the output. The fields in a collection +value are below: + +- `name` - The name of the output, also the index key. +- `change` - The data describing the change that will be made to this output. + For more details, see [Change Representation](#change-representation). + +## The `raw` Collection + +The `raw` collection exposes the raw, unprocessed plan data, direct from the +data stored by HCP Terraform. + +This is the same data that is produced by [`terraform show -json`](/terraform/cli/commands/show#json-output) on the plan file for the run this +policy check is attached to. + +Use of this data is only recommended in expert situations where the data the +collections present may not exactly serve the needs of the policy. For more +information on the file format, see the [JSON Output +Format](/terraform/internals/json-format) page. + +-> **NOTE:** Although designed to be relatively stable, the actual makeup for +the JSON output format is a Terraform CLI concern and as such not managed by +HCP Terraform. Use at your own risk, follow the [Terraform CLI +project](https://github.com/hashicorp/terraform), and watch the file format +documentation for any changes. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfplan.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfplan.mdx new file mode 100644 index 0000000000..12832dd583 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfplan.mdx @@ -0,0 +1,604 @@ +--- +page_title: tfplan Sentinel import reference +description: Use the tfplan import to give Sentinel access to a Terraform plan. +source: terraform-docs-common +--- + +# tfplan Sentinel import reference + +~> **Warning:** The `tfplan` import is now deprecated and will be permanently removed in August 2025. We recommend that you start using the updated [tfplan/v2](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import as soon as possible to avoid disruptions. The `tfplan/v2` import offers improved functionality and is designed to better support your policy enforcement needs. + +The `tfplan` import provides access to a Terraform plan. A Terraform plan is the +file created as a result of `terraform plan` and is the input to `terraform +apply`. The plan represents the changes that Terraform needs to make to +infrastructure to reach the desired state represented by the configuration. + +In addition to the diff data available in the plan, there is an +[`applied`](#value-applied) state available that merges the plan with the state +to create the planned state after apply. + +Finally, this import also allows you to access the configuration files and the +Terraform state at the time the plan was run. See the section on [accessing a +plan's state and configuration +data](#accessing-a-plan-39-s-state-and-configuration-data) for more information. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Namespace Overview + +The following is a tree view of the import namespace. For more detail on a +particular part of the namespace, see below. + +-> Note that the root-level alias keys shown here (`data`, `path`, and +`resources`) are shortcuts to a [module namespace](#namespace-module) scoped to +the root module. For more details, see the section on [root namespace +aliases](#root-namespace-aliases). + + tfplan + ├── module() (function) + │ └── (module namespace) + │ ├── path ([]string) + │ ├── data + │ │ └── TYPE.NAME[NUMBER] + │ │ ├── applied (map of keys) + │ │ └── diff + │ │ └── KEY + │ │ ├── computed (bool) + │ │ ├── new (string) + │ │ └── old (string) + │ └── resources + │ └── TYPE.NAME[NUMBER] + │ ├── applied (map of keys) + │ ├── destroy (bool) + │ ├── requires_new (bool) + │ └── diff + │ └── KEY + │ ├── computed (bool) + │ ├── new (string) + │ └── old (string) + ├── module_paths ([][]string) + ├── terraform_version (string) + ├── variables (map of keys) + │ + ├── data (root module alias) + ├── path (root module alias) + ├── resources (root module alias) + │ + ├── config (tfconfig namespace alias) + └── state (tfstate import alias) + +## Namespace: Root + +The root-level namespace consists of the values and functions documented below. + +In addition to this, the root-level `data`, `path`, and `resources` keys alias +to their corresponding namespaces or values within the [module +namespace](#namespace-module). + +### Accessing a Plan's State and Configuration Data + +The `config` and `state` keys alias to the [`tfconfig`][import-tfconfig] and +[`tfstate`][import-tfstate] namespaces, respectively, with the data sourced from +the Terraform _plan_ (as opposed to actual configuration and state). + +[import-tfconfig]: /terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2 + +[import-tfstate]: /terraform/enterprise/policy-enforcement/import-reference/tfstate-v2 + +-> Note that these aliases are not represented as maps. While they will appear +empty when viewed as maps, the specific import namespace keys will still be +accessible. + +-> Note that while current versions of HCP Terraform source configuration and +state data from the plan for the Terraform run in question, future versions may +source data accessed through the `tfconfig` and `tfstate` imports (as opposed to +`tfplan.config` and `tfplan.state`) from actual config bundles, or state as +stored by HCP Terraform. When this happens, the distinction here will be useful - +the data in the aliased namespaces will be the config and state data as the +_plan_ sees it, versus the actual "physical" data. + +### Function: `module()` + + module = func(ADDR) + +- **Return Type:** A [module namespace](#namespace-module). + +The `module()` function in the [root namespace](#namespace-root) returns the +[module namespace](#namespace-module) for a particular module address. + +The address must be a list and is the module address, split on the period (`.`), +excluding the root module. + +Hence, a module with an address of simply `foo` (or `root.foo`) would be +`["foo"]`, and a module within that (so address `foo.bar`) would be read as +`["foo", "bar"]`. + +[`null`][ref-null] is returned if a module address is invalid, or if the module +is not present in the diff. + +[ref-null]: /sentinel/docs/language/spec#null + +As an example, given the following module block: + +```hcl +module "foo" { + # ... +} +``` + +If the module contained the following content: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfplan" + +main = rule { tfplan.module(["foo"]).resources.null_resource.foo[0].applied.triggers.foo is "bar" } +``` + +### Value: `module_paths` + +- **Value Type:** List of a list of strings. + +The `module_paths` value within the [root namespace](#namespace-root) is a list +of all of the modules within the Terraform diff for the current plan. + +Modules not present in the diff will not be present here, even if they are +present in the configuration or state. + +This data is represented as a list of a list of strings, with the inner list +being the module address, split on the period (`.`). + +The root module is included in this list, represented as an empty inner list, as +long as there are changes. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The value of `module_paths` would be: + + [ + [], + ["foo"], + ] + +And the following policy would evaluate to `true`: + +```python +import "tfplan" + +main = rule { tfplan.module_paths contains ["foo"] } +``` + +-> Note the above example only applies if the module is present in the diff. + +#### Iterating Through Modules + +Iterating through all modules to find particular resources can be useful. This +[example][iterate-over-modules] shows how to use `module_paths` with the +[`module()` function](#function-module-) to find all resources of a +particular type from all modules that have pending changes using the `tfplan` +import. + +[iterate-over-modules]: /terraform/enterprise/policy-enforcement/sentinel#sentinel-imports + +### Value: `terraform_version` + +- **Value Type:** String. + +The `terraform_version` value within the [root namespace](#namespace-root) +represents the version of Terraform used to create the plan. This can be used to +enforce a specific version of Terraform in a policy check. + +As an example, the following policy would evaluate to `true`, as long as the +plan was made with a version of Terraform in the 0.11.x series, excluding any +pre-release versions (example: `-beta1` or `-rc1`): + +```python +import "tfplan" + +main = rule { tfplan.terraform_version matches "^0\\.11\\.\\d+$" } +``` + +### Value: `variables` + +- **Value Type:** A string-keyed map of values. + +The `variables` value within the [root namespace](#namespace-root) represents +all of the variables that were set when creating the plan. This will only +contain variables set for the root module. + +Note that unlike the [`default`][import-tfconfig-variables-default] value in the +[`tfconfig` variables namespace][import-tfconfig-variables], primitive values +here are stringified, and type conversion will need to be performed to perform +comparison for int, float, or boolean values. This only applies to variables +that are primitives themselves and not primitives within maps and lists, which +will be their original types. + +[import-tfconfig-variables-default]: /terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2#value-default + +[import-tfconfig-variables]: /terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2#namespace-variables + +If a default was accepted for the particular variable, the default value will be +populated here. + +As an example, given the following variable blocks: + +```hcl +variable "foo" { + default = "bar" +} + +variable "number" { + default = 42 +} + +variable "map" { + default = { + foo = "bar" + number = 42 + } +} +``` + +The following policy would evaluate to `true`, if no values were entered to +change these variables: + +```python +import "tfplan" + +default_foo = rule { tfplan.variables.foo is "bar" } +default_number = rule { tfplan.variables.number is "42" } +default_map_string = rule { tfplan.variables.map["foo"] is "bar" } +default_map_int = rule { tfplan.variables.map["number"] is 42 } + +main = rule { default_foo and default_number and default_map_string and default_map_int } +``` + +## Namespace: Module + +The **module namespace** can be loaded by calling +[`module()`](#function-module-) for a particular module. + +It can be used to load the following child namespaces, in addition to the values +documented below: + +- `data` - Loads the [resource namespace](#namespace-resources-data-sources), + filtered against data sources. +- `resources` - Loads the [resource + namespace](#namespace-resources-data-sources), filtered against resources. + +### Root Namespace Aliases + +The root-level `data` and `resources` keys both alias to their corresponding +namespaces within the module namespace, loaded for the root module. They are the +equivalent of running `module([]).KEY`. + +### Value: `path` + +- **Value Type:** List of strings. + +The `path` value within the [module namespace](#namespace-module) contains the +path of the module that the namespace represents. This is represented as a list +of strings. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The following policy would evaluate to `true` _only_ if the diff had changes for +that module: + +```python +import "tfplan" + +main = rule { tfplan.module(["foo"]).path contains "foo" } +``` + +## Namespace: Resources/Data Sources + +The **resource namespace** is a namespace _type_ that applies to both resources +(accessed by using the `resources` namespace key) and data sources (accessed +using the `data` namespace key). + +Accessing an individual resource or data source within each respective namespace +can be accomplished by specifying the type, name, and resource number (as if the +resource or data source had a `count` value in it) in the syntax +`[resources|data].TYPE.NAME[NUMBER]`. Note that NUMBER is always needed, even if +you did not use `count` in the resource. + +In addition, each of these namespace levels is a map, allowing you to filter +based on type and name. + +-> The (somewhat strange) notation here of `TYPE.NAME[NUMBER]` may imply that +the inner resource index map is actually a list, but it's not - using the square +bracket notation over the dotted notation (`TYPE.NAME.NUMBER`) is required here +as an identifier cannot start with a number. + +Some examples of multi-level access are below: + +- To fetch all `aws_instance.foo` resource instances within the root module, you + can specify `tfplan.resources.aws_instance.foo`. This would then be indexed by + resource count index (`0`, `1`, `2`, and so on). Note that as mentioned above, + these elements must be accessed using square-bracket map notation (so `[0]`, + `[1]`, `[2]`, and so on) instead of dotted notation. +- To fetch all `aws_instance` resources within the root module, you can specify + `tfplan.resources.aws_instance`. This would be indexed from the names of + each resource (`foo`, `bar`, and so on), with each of those maps containing + instances indexed by resource count index as per above. +- To fetch all resources within the root module, irrespective of type, use + `tfplan.resources`. This is indexed by type, as shown above with + `tfplan.resources.aws_instance`, with names being the next level down, and so + on. + +~> When [resource targeting](/terraform/cli/commands/plan#resource-targeting) is in effect, `tfplan.resources` will only include the resources specified as targets for the run. This may lead to unexpected outcomes if a policy expects a resource to be present in the plan. To prohibit targeted runs altogether, ensure [`tfrun.target_addrs`](/terraform/enterprise/policy-enforcement/import-reference/tfrun#value-target_addrs) is undefined or empty. + +Further explanation of the namespace will be in the context of resources. As +mentioned, when operating on data sources, use the same syntax, except with +`data` in place of `resources`. + +### Value: `applied` + +- **Value Type:** A string-keyed map of values. + +The `applied` value within the [resource +namespace](#namespace-resources-data-sources) contains a "predicted" +representation of the resource's state post-apply. It's created by merging the +pending resource's diff on top of the existing data from the resource's state +(if any). The map is a complex representation of these values with data going +as far down as needed to represent any state values such as maps, lists, and +sets. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if the resource was in the diff: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].applied.triggers.foo is "bar" } +``` + +-> Note that some values will not be available in the `applied` state because +they cannot be known until the plan is actually applied. In Terraform 0.11 or +earlier, these values are represented by a placeholder (the UUID value +`74D93920-ED26-11E3-AC10-0800200C9A66`) and in Terraform 0.12 or later they +are `undefined`. **In either case**, you should instead use the +[`computed`](#value-computed) key within the [diff +namespace](#namespace-resource-diff) to determine that a computed value will +exist. + +-> If a resource is being destroyed, its `applied` value is omitted from the +namespace and trying to fetch it will return undefined. + +### Value: `diff` + +- **Value Type:** A map of [diff namespaces](#namespace-resource-diff). + +The `diff` value within the [resource +namespace](#namespace-resources-data-sources) contains the diff for a particular +resource. Each key within the map links to a [diff +namespace](#namespace-resource-diff) for that particular key. + +Note that unlike the [`applied`](#value-applied) value, this map is not complex; +the map is only 1 level deep with each key possibly representing a diff for a +particular complex value within the resource. + +See the below section for more details on the diff namespace, in addition to +usage examples. + +### Value: `destroy` + +- **Value Type:** Boolean. + +The `destroy` value within the [resource +namespace](#namespace-resources-data-sources) is `true` if a resource is being +destroyed for _any_ reason, including cases where it's being deleted as part of +a resource re-creation, in which case [`requires_new`](#value-requires_new) will +also be set. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` when `null_resource.foo` is being +destroyed: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].destroy } +``` + +### Value: `requires_new` + +- **Value Type:** Boolean. + +The `requires_new` value within the [resource +namespace](#namespace-resources-data-sources) is `true` if the resource is still +present in the configuration, but must be replaced to satisfy its current diff. +Whenever `requires_new` is `true`, [`destroy`](#value-destroy) is also `true`. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if one of the `triggers` in +`null_resource.foo` was being changed: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].requires_new } +``` + +## Namespace: Resource Diff + +The **diff namespace** is a namespace that represents the diff for a specific +attribute within a resource. For details on reading a particular attribute, +see the [`diff`](#value-diff) value in the [resource +namespace](#namespace-resources-data-sources). + +### Value: `computed` + +- **Value Type:** Boolean. + +The `computed` value within the [diff namespace](#namespace-resource-diff) is +`true` if the resource key in question depends on another value that isn't yet +known. Typically, that means the value it depends on belongs to a resource that +either doesn't exist yet, or is changing state in such a way as to affect the +dependent value so that it can't be known until the apply is complete. + +-> Keep in mind that when using `computed` with complex structures such as maps, +lists, and sets, it's sometimes necessary to test the count attribute for the +structure, versus a key within it, depending on whether or not the diff has +marked the whole structure as computed. This is demonstrated in the example +below. Count keys are `%` for maps, and `#` for lists and sets. If you are +having trouble determining the type of specific field within a resource, contact +the support team. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} + +resource "null_resource" "bar" { + triggers = { + foo_id = "${null_resource.foo.id}" + } +} +``` + +The following policy would evaluate to `true`, if the `id` of +`null_resource.foo` was currently not known, such as when the resource is +pending creation, or is being deleted and re-created: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.bar[0].diff["triggers.%"].computed } +``` + +### Value: `new` + +- **Value Type:** String. + +The `new` value within the [diff namespace](#namespace-resource-diff) contains +the new value of a changing attribute, _if_ the value is known at plan time. + +-> `new` will be an empty string if the attribute's value is currently unknown. +For more details on detecting unknown values, see [`computed`](#value-computed). + +Note that this value is _always_ a string, regardless of the actual type of the +value changing. [Type conversion][ref-sentinel-type-conversion] within policy +may be necessary to achieve the comparison needed. + +[ref-sentinel-type-conversion]: /sentinel/docs/language/values#type-conversion + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`, if the resource was in the diff +and each of the concerned keys were changing to new values: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].diff["triggers.foo"].new is "bar" } +``` + +### Value: `old` + +- **Value Type:** String. + +The `old` value within the [diff namespace](#namespace-resource-diff) contains +the old value of a changing attribute. + +Note that this value is _always_ a string, regardless of the actual type of the +value changing. [Type conversion][ref-sentinel-type-conversion] within policy +may be necessary to achieve the comparison needed. + +If the value did not exist in the previous state, `old` will always be an empty +string. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "baz" + } +} +``` + +If that resource was previously in config as: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].diff["triggers.foo"].old is "bar" } +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfrun.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfrun.mdx new file mode 100644 index 0000000000..51d03dfd0e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfrun.mdx @@ -0,0 +1,320 @@ +--- +page_title: tfrun Sentinel import reference +description: >- + Use tfrun import to give Sentinel access to data associated with a Terraform + run. +source: terraform-docs-common +--- + +# tfrun Sentinel import reference + +The `tfrun` import provides access to data associated with a [Terraform run][run-glossary]. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +This import currently consists of run attributes, as well as namespaces for the `organization`, `workspace` and `cost-estimate`. Each namespace provides static data regarding the HCP Terraform application that can then be consumed by Sentinel during a policy evaluation. + + tfrun + ├── id (string) + ├── created_at (string) + ├── created_by (string) + ├── message (string) + ├── commit_sha (string) + ├── is_destroy (boolean) + ├── refresh (boolean) + ├── refresh_only (boolean) + ├── replace_addrs (array of strings) + ├── speculative (boolean) + ├── target_addrs (array of strings) + ├── project + │ ├── id (string) + │ └── name (string) + ├── variables (map of keys) + ├── organization + │ └── name (string) + ├── workspace + │ ├── id (string) + │ ├── name (string) + │ ├── created_at (string) + │ ├── description (string) + │ ├── execution_mode (string) + │ ├── auto_apply (bool) + │ ├── tags (array of strings) + | ├── tag_bindings (array of objects) + │ ├── working_directory (string) + │ └── vcs_repo (map of keys) + └── cost_estimate + ├── prior_monthly_cost (string) + ├── proposed_monthly_cost (string) + └── delta_monthly_cost (string) + +-> **Note:** When writing policies using this import, keep in mind that workspace +data is generally editable by users outside of the context of policy +enforcement. For example, consider the case of omitting the enforcement of +policy rules for development workspaces by the workspace name (allowing the +policy to pass if the workspace ends in `-dev`). While this is useful for +extremely granular exceptions, the workspace name could be edited by +workspace admins, effectively bypassing the policy. In this case, where an +extremely strict separation of policy managers vs. workspace practitioners is +required, using [policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) +to only enforce the policy on non-development workspaces is more appropriate. + +[run-glossary]: /terraform/docs/glossary#run + +[workspace-glossary]: /terraform/docs/glossary#workspace + +## Namespace: root + +The **root namespace** contains data associated with the current run. + +### Value: `id` + +- **Value Type:** String. + +Specifies the ID that is associated with the current Terraform run. + +### Value: `created_at` + +- **Value Type:** String. + +The `created_at` value within the [root namespace](#namespace-root) specifies the time that the run was created. The timestamp returned follows the format outlined in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). + +Users can use the `time` import to [load](/sentinel/docs/imports/time#time-load-timeish) a run timestamp and create a new timespace from the specified value. See the `time` import [documentation](/sentinel/docs/imports/time#import-time) for available actions that can be performed on timespaces. + +### Value: `created_by` + +- **Value Type:** String. + +The `created_by` value within the [root namespace](#namespace-root) is string that specifies the user name of the HCP Terraform user for the specific run. + +### Value: `message` + +- **Value Type:** String. + +Specifies the message that is associated with the Terraform run. + +The default value is _"Queued manually via the Terraform Enterprise API"_. + +### Value: `commit_sha` + +- **Value Type:** String. + +Specifies the checksum hash (SHA) that identifies the commit. + +### Value: `is_destroy` + +- **Value Type:** Boolean. + +Specifies if the plan is a destroy plan, which will destroy all provisioned resources. + +### Value: `refresh` + +- **Value Type:** Boolean. + +Specifies whether the state was refreshed prior to the plan. + +### Value: `refresh_only` + +- **Value Type:** Boolean. + +Specifies whether the plan is in refresh-only mode, which ignores configuration changes and updates state with any changes made outside of Terraform. + +### Value: `replace_addrs` + +- **Value Type:** An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing). + +Provides the targets specified using the [`-replace`](/terraform/cli/commands/plan#resource-targeting) flag in the CLI or the `replace-addrs` attribute in the API. Will be null if no resource targets are specified. + +### Value: `speculative` + +- **Value Type:** Boolean. + +Specifies whether the plan associated with the run is a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) only. + +### Value: `target_addrs` + +- **Value Type:** An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing). + +Provides the targets specified using the [`-target`](/terraform/cli/commands/plan#resource-targeting) flag in the CLI or the `target-addrs` attribute in the API. Will be null if no resource targets are specified. + +To prohibit targeted runs altogether, make sure the `target_addrs` value is null or empty: + + import "tfrun" + + main = tfrun.target_addrs is null or tfrun.target_addrs is empty + +### Value: `variables` + +- **Value Type:** A string-keyed map of values. + +Provides the names of the variables that are configured within the run and the [sensitivity](/terraform/enterprise/workspaces/variables/managing-variables#sensitive-values) state of the value. + + variables (map of keys) + └── name (string) + └── category (string) + └── sensitive (boolean) + +## Namespace: project + +The **project namespace** contains data associated with the current run's [projects](/terraform/enterprise/api-docs/projects). + +### Value: `id` + +- **Value Type:** String. + +Specifies the ID that is associated with the current project. + +### Value: `name` + +- **Value Type:** String. + +Specifies the name assigned to the HCP Terraform project. + +## Namespace: organization + +The **organization namespace** contains data associated with the current run's HCP Terraform [organization](/terraform/enterprise/users-teams-organizations/organizations). + +### Value: `name` + +- **Value Type:** String. + +Specifies the name assigned to the HCP Terraform organization. + +## Namespace: workspace + +The **workspace namespace** contains data associated with the current run's workspace. + +### Value: `id` + +- **Value Type:** String. + +Specifies the ID that is associated with the Terraform workspace. + +### Value: `name` + +- **Value Type:** String. + +The name of the workspace, which can only include letters, numbers, `-`, and `_`. + +As an example, in a workspace named `app-us-east-dev` the following policy would evaluate to `true`: + + # Enforces production rules on all non-development workspaces + + import "tfrun" + import "strings" + + # (Actual policy logic omitted) + evaluate_production_policy = rule { ... } + + main = rule when strings.has_suffix(tfrun.workspace.name, "-dev") is false { + evaluate_production_policy + } + +### Value: `created_at` + +- **Value Type:** String. + +Specifies the time that the workspace was created. The timestamp returned follows the format outlined in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). + +Users can use the `time` import to [load](/sentinel/docs/imports/time#time-load-timeish) a workspace timestamp, and create a new timespace from the specified value. See the `time` import [documentation](/sentinel/docs/imports/time#import-time) for available actions that can be performed on timespaces. + +### Value: `description` + +- **Value Type:** String. + +Contains the description for the workspace. + +This value can be `null`. + +### Value: `auto_apply` + +- **Value Type:** Boolean. + +Contains the workspace's [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) setting. + +### Value: `tags` + +- **Value Type:** Array of strings. + +Contains the list of tag names for the workspace, as well as the keys from tag bindings. + +### Value: `tag_bindings` + +- **Value Type:** Array of objects. + +Contains the complete list of tag bindings for the workspace, which includes inherited tag bindings, as well as the workspace key-only tags. Each binding has a string `key`, a nullable string `value`, as well as a boolean `inherited` properties. + + tag_bindings (array of objects) + ├── key (string) + ├── value (string or null) + └── inherited (boolean) + +### Value: `working_directory` + +- **Value Type:** String. + +Contains the configured [Terraform working directory](/terraform/enterprise/workspaces/settings#terraform-working-directory) of the workspace. + +This value can be `null`. + +### Value: `execution_mode` + +- **Value Type:** String. + +Contains the configured [Terraform execution mode](/terraform/enterprise/workspaces/settings#execution-mode) of the workspace. + +The default value is `remote`. + +### Value: `vcs_repo` + +- **Value Type:** A string-keyed map of values. + +Contains data associated with a VCS repository connected to the workspace. + +Details regarding each attribute can be found in the documentation for the HCP Terraform [Workspaces API](/terraform/enterprise/api-docs/workspaces). + +This value can be `null`. + + vcs_repo (map of keys) + ├── identifier (string) + ├── display_identifier (string) + ├── branch (string) + └── ingress_submodules (bool) + +## Namespace: cost_estimate + +The **cost_estimation namespace** contains data associated with the current run's cost estimate. + +This namespace is only present if a cost estimate is available. + +-> Cost estimation is disabled for runs using [resource targeting](/terraform/cli/commands/plan#resource-targeting), which may cause unexpected failures. + +-> **Note:** Cost estimates are not available for Terraform 0.11. + +### Value: `prior_monthly_cost` + +- **Value Type:** String. + +Contains the monthly cost estimate at the beginning of a plan. + +This value contains a positive decimal and can be `"0.0"`. + +### Value: `proposed_monthly_cost` + +- **Value Type:** String. + +Contains the monthly cost estimate if the plan were to be applied. + +This value contains a positive decimal and can be `"0.0"`. + +### Value: `delta_monthly_cost` + +- **Value Type:** String. + +Contains the difference between the prior and proposed monthly cost estimates. + +This value may contain a positive or negative decimal and can be `"0.0"`. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfstate-v2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfstate-v2.mdx new file mode 100644 index 0000000000..0de4f5cbd5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfstate-v2.mdx @@ -0,0 +1,180 @@ +--- +page_title: tfstate/v2 Sentinel import +description: Use tfstate/v2 import to give Sentinel access to Terraform state. +source: terraform-docs-common +--- + +-> **Note:** This is documentation for the next version of the `tfstate` +Sentinel import, designed specifically for Terraform 0.12. This import requires +Terraform 0.12 or higher, and must currently be loaded by path, using an alias, +example: `import "tfstate/v2" as tfstate`. + +# tfstate/v2 Sentinel import + +The `tfstate/v2` import provides access to a Terraform state. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +The _state_ is the data that Terraform has recorded about a workspace at a +particular point in its lifecycle, usually after an apply. You can read more +general information about how Terraform uses state +[here](/terraform/language/state). + +-> **NOTE:** Since HCP Terraform currently only supports policy checks at plan +time, the usefulness of this import is somewhat limited, as it will usually give +you the state _prior_ to the plan the policy check is currently being run for. +Depending on your needs, you may find the +[`planned_values`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-planned_values-collection) collection in +`tfplan/v2` more useful, which will give you a _predicted_ state by applying +plan data to the data found here. The one exception to this rule is _data +sources_, which will always give up to date data here, as long as the data +source could be evaluated at plan time. + +The data in the `tfstate/v2` import is sourced from the JSON configuration file +that is generated by the [`terraform show -json`](/terraform/cli/commands/show#json-output) command. For more information on +the file format, see the [JSON Output Format](/terraform/internals/json-format) +page. + +## Import Overview + +The `tfstate/v2` import is structured as currently two _collections_, keyed in +resource address and output name, respectively. + + (tfstate/v2) + ├── terraform_version (string) + ├── resources + │ └── (indexed by address) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── index (float (number) or string) + │ ├── provider_name (string) + │ ├── values (map) + │ ├── depends_on (list of strings) + │ ├── tainted (boolean) + │ └── deposed_key (string) + └── outputs + └── (indexed by name) + ├── name (string) + ├── sensitive (boolean) + └── value (value) + +The collections are: + +- [`resources`](#the-resources-collection) - The state of all resources across + all modules in the state. +- [`outputs`](#the-outputs-collection) - The state of all outputs from the root module in the state. + +These collections are specifically designed to be used with the +[`filter`](/sentinel/docs/language/collection-operations#filter-expression) +quantifier expression in Sentinel, so that one can collect a list of resources +to perform policy checks on without having to write complex module traversal. As +an example, the following code will return all `aws_instance` resource types +within the state, regardless of what module they are in: + + all_aws_instances = filter tfstate.resources as _, r { + r.mode is "managed" and + r.type is "aws_instance" + } + +You can add specific attributes to the filter to narrow the search, such as the +module address. The following code would return resources in a module named +`foo` only: + + all_aws_instances = filter tfstate.resources as _, r { + r.module_address is "module.foo" and + r.mode is "managed" and + r.type is "aws_instance" + } + +## The `terraform_version` Value + +The top-level `terraform_version` value in this import gives the Terraform +version that recorded the state. This can be used to do version validation. + + import "tfstate/v2" as tfstate + import "strings" + + v = strings.split(tfstate.terraform_version, ".") + version_major = int(v[1]) + version_minor = int(v[2]) + + main = rule { + version_major is 12 and version_minor >= 19 + } + +-> **NOTE:** The above example will give errors when working with pre-release +versions (example: `0.12.0beta1`). Future versions of this import will include +helpers to assist with processing versions that will account for these kinds of +exceptions. + +## The `resources` Collection + +The `resources` collection is a collection representing all of the resources in +the state, across all modules. + +This collection is indexed on the complete resource address as the key. + +An element in the collection has the following values: + +- `address` - The absolute resource address - also the key for the collection's + index. + +- `module_address` - The address portion of the absolute resource address. + +- `mode` - The resource mode, either `managed` (resources) or `data` (data + sources). + +- `type` - The resource type, example: `aws_instance` for `aws_instance.foo`. + +- `name` - The resource name, example: `foo` for `aws_instance.foo`. + +- `index` - The resource index. Can be either a number or a string. + +- `provider_name` - The name of the provider this resource belongs to. This + allows the provider to be interpreted unambiguously in the unusual situation + where a provider offers a resource type whose name does not start with its own + name, such as the `googlebeta` provider offering `google_compute_instance`. + + -> **Note:** Starting with Terraform 0.13, the `provider_name` field contains the + _full_ source address to the provider in the Terraform Registry. Example: + `registry.terraform.io/hashicorp/null` for the null provider. + +- `values` - An object (map) representation of the attribute values of the + resource, whose structure depends on the resource type schema. When accessing + proposed state through the [`planned_values`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-planned_values-collection) + collection of the tfplan/v2 import, unknown values will be omitted. + +- `depends_on` - The addresses of the resources that this resource depends on. + +- `tainted` - `true` if the resource has been explicitly marked as + [tainted](/terraform/cli/commands/taint) in the state. + +- `deposed_key` - Set if the resource has been marked deposed and will be + destroyed on the next apply. This matches the deposed field in the + [`resource_changes`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-resource_changes-collection) + collection in the [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import. + +## The `outputs` Collection + +The `outputs` collection is a collection of outputs from the root module of the +state. + +Note that no child modules are included in this output set, and there is no way +to fetch child module output values. This is to encourage the correct flow of +outputs to the recommended root consumption level. + +The collection is indexed on the output name, with the following fields: + +- `name`: The name of the output, also the collection key. +- `sensitive`: Whether or not the value was marked as + [sensitive](/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output) + in + configuration. +- `value`: The value of the output. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfstate.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfstate.mdx new file mode 100644 index 0000000000..42e2590196 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/import-reference/tfstate.mdx @@ -0,0 +1,550 @@ +--- +page_title: tfstate Sentinel import +description: Use the tfstate import to give Sentinel access to Terraform state. +source: terraform-docs-common +--- + +# Import: tfstate + +~> **Warning:** The `tfstate` import is now deprecated and will be permanently removed in August 2025. We recommend that you start using the updated [tfstate/v2](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) import as soon as possible to avoid disruptions. The `tfstate/v2` import offers improved functionality and is designed to better support your policy enforcement needs. + +The `tfstate` import provides access to the Terraform state. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +The _state_ is the data that Terraform has recorded about a workspace at a +particular point in its lifecycle, usually after an apply. You can read more +general information about how Terraform uses state [here][ref-tf-state]. + +[ref-tf-state]: /terraform/language/state + +-> **Note:** Since HCP Terraform currently only supports policy checks at plan +time, the usefulness of this import is somewhat limited, as it will usually give +you the state _prior_ to the plan the policy check is currently being run for. +Depending on your needs, you may find the +[`applied`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#value-applied) collection in `tfplan` more useful, +which will give you a _predicted_ state by applying plan data to the data found +here. The one exception to this rule is _data sources_, which will always give +up to date data here, as long as the data source could be evaluated at plan +time. + +## Namespace Overview + +The following is a tree view of the import namespace. For more detail on a +particular part of the namespace, see below. + +-> Note that the root-level alias keys shown here (`data`, `outputs`, `path`, +and `resources`) are shortcuts to a [module namespace](#namespace-module) scoped +to the root module. For more details, see the section on [root namespace +aliases](#root-namespace-aliases). + + tfstate + ├── module() (function) + │ └── (module namespace) + │ ├── path ([]string) + │ ├── data + │ │ └── TYPE.NAME[NUMBER] + │ │ ├── attr (map of keys) + │ │ ├── depends_on ([]string) + │ │ ├── id (string) + │ │ └── tainted (boolean) + │ ├── outputs (root module only in TF 0.12 or later) + │ │ └── NAME + │ │ ├── sensitive (bool) + │ │ ├── type (string) + │ │ └── value (value) + │ └── resources + │ └── TYPE.NAME[NUMBER] + │ ├── attr (map of keys) + │ ├── depends_on ([]string) + │ ├── id (string) + │ └── tainted (boolean) + │ + ├── module_paths ([][]string) + ├── terraform_version (string) + │ + ├── data (root module alias) + ├── outputs (root module alias) + ├── path (root module alias) + └── resources (root module alias) + +## Namespace: Root + +The root-level namespace consists of the values and functions documented below. + +In addition to this, the root-level `data`, `outputs`, `path`, and `resources` +keys alias to their corresponding namespaces or values within the [module +namespace](#namespace-module). + +### Function: `module()` + + module = func(ADDR) + +- **Return Type:** A [module namespace](#namespace-module). + +The `module()` function in the [root namespace](#namespace-root) returns the +[module namespace](#namespace-module) for a particular module address. + +The address must be a list and is the module address, split on the period (`.`), +excluding the root module. + +Hence, a module with an address of simply `foo` (or `root.foo`) would be +`["foo"]`, and a module within that (so address `foo.bar`) would be read as +`["foo", "bar"]`. + +[`null`][ref-null] is returned if a module address is invalid, or if the module +is not present in the state. + +[ref-null]: /sentinel/docs/language/spec#null + +As an example, given the following module block: + +```hcl +module "foo" { + # ... +} +``` + +If the module contained the following content: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if the resource was present in +the state: + +```python +import "tfstate" + +main = rule { tfstate.module(["foo"]).resources.null_resource.foo[0].attr.triggers.foo is "bar" } +``` + +### Value: `module_paths` + +- **Value Type:** List of a list of strings. + +The `module_paths` value within the [root namespace](#namespace-root) is a list +of all of the modules within the Terraform state at plan-time. + +Modules not present in the state will not be present here, even if they are +present in the configuration or the diff. + +This data is represented as a list of a list of strings, with the inner list +being the module address, split on the period (`.`). + +The root module is included in this list, represented as an empty inner list, as +long as it is present in state. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The value of `module_paths` would be: + + [ + [], + ["foo"], + ] + +And the following policy would evaluate to `true`: + +```python +import "tfstate" + +main = rule { tfstate.module_paths contains ["foo"] } +``` + +-> Note the above example only applies if the module is present in the state. + +#### Iterating Through Modules + +Iterating through all modules to find particular resources can be useful. This +[example][iterate-over-modules] shows how to use `module_paths` with the +[`module()` function](#function-module-) to find all resources of a +particular type from all modules using the `tfplan` import. By changing `tfplan` +in this function to `tfstate`, you could make a similar function find all +resources of a specific type in the current state. + +[iterate-over-modules]: /terraform/enterprise/policy-enforcement/sentinel#sentinel-imports + +### Value: `terraform_version` + +- **Value Type:** String. + +The `terraform_version` value within the [root namespace](#namespace-root) +represents the version of Terraform in use when the state was saved. This can be +used to enforce a specific version of Terraform in a policy check. + +As an example, the following policy would evaluate to `true` as long as the +state was made with a version of Terraform in the 0.11.x series, excluding any +pre-release versions (example: `-beta1` or `-rc1`): + +```python +import "tfstate" + +main = rule { tfstate.terraform_version matches "^0\\.11\\.\\d+$" } +``` + +-> **NOTE:** This value is also available via the [`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) +import, which will be more current when a policy check is run against a plan. +It's recommended you use the value in `tfplan` until HCP Terraform +supports policy checks in other stages of the workspace lifecycle. See the +[`terraform_version`][import-tfplan-terraform-version] reference within the +`tfplan` import for more details. + +[import-tfplan-terraform-version]: /terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#value-terraform_version + +## Namespace: Module + +The **module namespace** can be loaded by calling +[`module()`](#function-module-) for a particular module. + +It can be used to load the following child namespaces, in addition to the values +documented below: + +- `data` - Loads the [resource namespace](#namespace-resources-data-sources), + filtered against data sources. +- `outputs` - Loads the [output namespace](#namespace-outputs), which supply the + outputs present in this module's state. Note that with Terraform 0.12 or + later, this value is only available for the root namespace. +- `resources` - Loads the [resource + namespace](#namespace-resources-data-sources), filtered against resources. + +### Root Namespace Aliases + +The root-level `data`, `outputs`, and `resources` keys both alias to their +corresponding namespaces within the module namespace, loaded for the root +module. They are the equivalent of running `module([]).KEY`. + +### Value: `path` + +- **Value Type:** List of strings. + +The `path` value within the [module namespace](#namespace-module) contains the +path of the module that the namespace represents. This is represented as a list +of strings. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The following policy would evaluate to `true`, _only_ if the module was present +in the state: + +```python +import "tfstate" + +main = rule { tfstate.module(["foo"]).path contains "foo" } +``` + +## Namespace: Resources/Data Sources + +The **resource namespace** is a namespace _type_ that applies to both resources +(accessed by using the `resources` namespace key) and data sources (accessed +using the `data` namespace key). + +Accessing an individual resource or data source within each respective namespace +can be accomplished by specifying the type, name, and resource number (as if the +resource or data source had a `count` value in it) in the syntax +`[resources|data].TYPE.NAME[NUMBER]`. Note that NUMBER is always needed, even if +you did not use `count` in the resource. + +In addition, each of these namespace levels is a map, allowing you to filter +based on type and name. + +-> The (somewhat strange) notation here of `TYPE.NAME[NUMBER]` may imply that +the inner resource index map is actually a list, but it's not - using the square +bracket notation over the dotted notation (`TYPE.NAME.NUMBER`) is required here +as an identifier cannot start with number. + +Some examples of multi-level access are below: + +- To fetch all `aws_instance.foo` resource instances within the root module, you + can specify `tfstate.resources.aws_instance.foo`. This would then be indexed + by resource count index (`0`, `1`, `2`, and so on). Note that as mentioned + above, these elements must be accessed using square-bracket map notation (so + `[0]`, `[1]`, `[2]`, and so on) instead of dotted notation. +- To fetch all `aws_instance` resources within the root module, you can specify + `tfstate.resources.aws_instance`. This would be indexed from the names of + each resource (`foo`, `bar`, and so on), with each of those maps containing + instances indexed by resource count index as per above. +- To fetch all resources within the root module, irrespective of type, use + `tfstate.resources`. This is indexed by type, as shown above with + `tfstate.resources.aws_instance`, with names being the next level down, and so + on. + +Further explanation of the namespace will be in the context of resources. As +mentioned, when operating on data sources, use the same syntax, except with +`data` in place of `resources`. + +### Value: `attr` + +- **Value Type:** A string-keyed map of values. + +The `attr` value within the [resource +namespace](#namespace-resources-data-sources) is a direct mapping to the state +of the resource. + +The map is a complex representation of these values with data going as far down +as needed to represent any state values such as maps, lists, and sets. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if the resource was in the state: + +```python +import "tfstate" + +main = rule { tfstate.resources.null_resource.foo[0].attr.triggers.foo is "bar" } +``` + +### Value: `depends_on` + +- **Value Type:** A list of strings. + +The `depends_on` value within the [resource +namespace](#namespace-resources-data-sources) contains the dependencies for the +resource. + +This is a list of full resource addresses, relative to the module (example: +`null_resource.foo`). + +As an example, given the following resources: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} + +resource "null_resource" "bar" { + # ... + + depends_on = [ + "null_resource.foo", + ] +} +``` + +The following policy would evaluate to `true` if the resource was in the state: + +```python +import "tfstate" + +main = rule { tfstate.resources.null_resource.bar[0].depends_on contains "null_resource.foo" } +``` + +### Value: `id` + +- **Value Type:** String. + +The `id` value within the [resource +namespace](#namespace-resources-data-sources) contains the id of the resource. + +-> **NOTE:** The example below uses a _data source_ here because the +[`null_data_source`][ref-tf-null-data-source] data source gives a static ID, +which makes documenting the example easier. As previously mentioned, data +sources share the same namespace as resources, but need to be loaded with the +`data` key. For more information, see the +[synopsis](#namespace-resources-data-sources) for the namespace itself. + +[ref-tf-null-data-source]: https://registry.terraform.io/providers/hashicorp/null/latest/docs/data-sources/data_source + +As an example, given the following data source: + +```hcl +data "null_data_source" "foo" { + # ... +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +main = rule { tfstate.data.null_data_source.foo[0].id is "static" } +``` + +### Value: `tainted` + +- **Value Type:** Boolean. + +The `tainted` value within the [resource +namespace](#namespace-resources-data-sources) is `true` if the resource is +marked as tainted in Terraform state. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`, if the resource was marked as +tainted in the state: + +```python +import "tfstate" + +main = rule { tfstate.resources.null_resource.foo[0].tainted } +``` + +## Namespace: Outputs + +The **output namespace** represents all of the outputs present within a +[module](#namespace-module). Outputs are present in a state if they were saved +during a previous apply, or if they were updated with known values during the +pre-plan refresh. + +**With Terraform 0.11 or earlier** this can be used to fetch both the outputs +of the root module, and the outputs of any module in the state below the root. +This makes it possible to see outputs that have not been threaded to the root +module. + +**With Terraform 0.12 or later** outputs are available in the top-level (root +module) namespace only and not accessible within submodules. + +This namespace is indexed by output name. + +### Value: `sensitive` + +- **Value Type:** Boolean. + +The `sensitive` value within the [output namespace](#namespace-outputs) is +`true` when the output has been [marked as sensitive][ref-tf-sensitive-outputs]. + +[ref-tf-sensitive-outputs]: /terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output + +As an example, given the following output: + +```hcl +output "foo" { + sensitive = true + value = "bar" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +main = rule { tfstate.outputs.foo.sensitive } +``` + +### Value: `type` + +- **Value Type:** String. + +The `type` value within the [output namespace](#namespace-outputs) gives the +output's type. This will be one of `string`, `list`, or `map`. These are +currently the only types available for outputs in Terraform. + +As an example, given the following output: + +```hcl +output "string" { + value = "foo" +} + +output "list" { + value = [ + "foo", + "bar", + ] +} + +output "map" { + value = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +type_string = rule { tfstate.outputs.string.type is "string" } +type_list = rule { tfstate.outputs.list.type is "list" } +type_map = rule { tfstate.outputs.map.type is "map" } + +main = rule { type_string and type_list and type_map } +``` + +### Value: `value` + +- **Value Type:** String, list, or map. + +The `value` value within the [output namespace](#namespace-outputs) is the value +of the output in question. + +Note that the only valid primitive output type in Terraform is currently a +string, which means that any int, float, or boolean value will need to be +converted before it can be used in comparison. This does not apply to primitives +within maps and lists, which will be their original types. + +As an example, given the following output blocks: + +```hcl +output "foo" { + value = "bar" +} + +output "number" { + value = "42" +} + +output "map" { + value = { + foo = "bar" + number = 42 + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +value_foo = rule { tfstate.outputs.foo.value is "bar" } +value_number = rule { int(tfstate.outputs.number.value) is 42 } +value_map_string = rule { tfstate.outputs.map.value["foo"] is "bar" } +value_map_int = rule { tfstate.outputs.map.value["number"] is 42 } + +main = rule { value_foo and value_number and value_map_string and value_map_int } +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/index.mdx new file mode 100644 index 0000000000..7a53f5ced2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/index.mdx @@ -0,0 +1,50 @@ +--- +page_title: Terraform Enterprise policy enforcement overview +description: >- + Policies are rules for provisioning infrastructure that you can use to + validate Terraform plans. Learn how to use Sentinel and OPA to enforce + policies. +source: terraform-docs-common +--- + +# HCP Terraform policy enforcement overview + +This topic provides overview information about policies in HCP Terraform. Policies are rules for Terraform runs that let you validate that Terraform plans comply with security rules and best practices. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +> **Hands-on:** Try the [Enforce Policy with Sentinel](/terraform/tutorials/policy) and [Detect Infrastructure Drift and Enforce OPA Policies](/terraform/tutorials/cloud/drift-and-opa) tutorials. + +## Introduction + +You can implement policies that check for any number of conditions, such as whether infrastructure configuration adheres to security standards or best practices. For example, you may want to write a policy to check whether Terraform plans to deploy production infrastructure to the correct region. + +You can also use policies to enforce standards for your organization’s workflows. For example, you could write a policy to prevent new infrastructure deployments on Fridays, reducing the risk of production incidents outside of your team’s working hours. + +## Workflow + +The following workflow describes how to create and manage policies manually. + +### Define policy + +You can use either the Sentinel or OPA framework to create custom policies. You can also copy pre-written Sentinel policies created and maintained by HashiCorp. + +### Create and apply policy sets + +Policy sets are collections of policies you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces in your organization. For each run in the selected workspaces, HCP Terraform checks the Terraform plan against the policy set. + +You can also exclude specific workspaces from global or project-scoped policy sets. HCP Terraform won't enforce a policy set's policies on any runs in an excluded workspace. For example, if you attach a policy set to a project and then exclude one of the project's workspaces from that policy set, HCP Terraform will not enforce the policy set on the excluded workspace. + +You can create policy sets from the [user interface](/terraform/enterprise/policy-enforcement/manage-policy-sets#create-policy-sets), the API, or by connecting HCP Terraform to your version control system. A policy set can only contain policies written in a single policy framework, but you can add Sentinel or OPA policy sets to the same workspace. + +Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. + +### Review policy results + +The HCP Terraform UI displays policy results for each policy set you apply to the workspace. Depending on their [enforcement level](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels), failed policies can stop the run. You can override failed policies with the right permissions. + +Refer to [Policy Results](/terraform/enterprise/policy-enforcement/view-results) for details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx new file mode 100644 index 0000000000..c5cf8a8a88 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx @@ -0,0 +1,219 @@ +--- +page_title: Manage policies and policy sets in Terraform Enterprise +description: >- + Learn how to create and manage policies and policy sets in Terraform + Enterprise. +source: terraform-docs-common +--- + +# Manage policies and policy sets in HCP Terraform + +Policies are rules that HCP Terraform enforces on Terraform runs. You can define policies using either the [Sentinel](/terraform/enterprise/policy-enforcement/sentinel) or [Open Policy Agent (OPA)](/terraform/enterprise/policy-enforcement/opa) policy-as-code frameworks. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policy sets are collections of policies you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces in your organization. For each run in the applicable workspaces, HCP Terraform checks the Terraform plan against the policy set. Depending on the [enforcement level](#policy-enforcement-levels), failed policies can stop a run in a workspace. If you do not want to enforce a policy set on a specific workspace, you can exclude the workspace from that set. + +## Permissions + +To view and manage policies and policy sets, you must have [manage policy permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-policies) for your organization. + +## Policy checks versus policy evaluations + +Policy checks and evaluations can access different types of data and enable slightly different workflows. + +### Policy checks + +Only Sentinel policies can run as policy checks. Checks can access cost estimation data but can only use the latest version of Sentinel. + +~> **Warning:** Policy checks are deprecated and will be permanently removed in August 2025. We recommend that you start using policy evaluations to avoid disruptions. + +### Policy evaluations + +OPA policy sets can only run as policy evaluations, and you can enable policy evaluations for Sentinel policy sets by selecting the `Agent` policy set type. Policy evaluations run within the [HCP Terraform agent](/terraform/cloud-docs/agents) in HCP Terraform's infrastructure. + +For Sentinel policy sets, using policy evaluations lets you: + +- Enable overrides for soft-mandatory and hard-mandatory policies, letting any user with [Manage Policy Overrides permission](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) proceed with a run in the event of policy failure. +- Select a specific Sentinel runtime version for the policy set. + +Policy evaluations **cannot** access cost estimation data, so use policy checks if your policies rely on cost estimates. + +~> **Tip:** Sentinel runtime version pinning is supported only for Sentinel 0.23.1 and above, as well as HCP Terraform agent versions 1.13.1 and above + +## Policy enforcement levels + +You can set an enforcement level for each policy that determines what happens when a Terraform plan does not pass the policy rule. Sentinel and OPA policies have different enforcement levels available. + +### Sentinel + +Sentinel provides three policy enforcement levels: + +- **advisory:** Failed policies never interrupt the run. They provide information about policy check failures in the UI. +- **soft mandatory:** Failed policies stop the run, but any user with [Manage Policy Overrides permission](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) can override these failures and allow the run to complete. +- **hard mandatory:** Failed policies stop the run. Terraform does not apply runs with failed **hard mandatory** policies until a user fixes the issue that caused the failure. + +### OPA + +OPA provides two policy enforcement levels: + +- **advisory** Failed policies never interrupt the run. They provide information about policy failures in the UI. +- **mandatory:** Failed policies stop the run, but any user with [Manage Policy Overrides permission](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) can override these failures and allow the run to complete. + +## Policy publishing workflows + +You can create policies and policy sets for your HCP Terraform organization in one of three ways: + +- **HCP Terraform web UI:** Add individually-managed policies manually in the HCP Terraform UI, and store your policy code in HCP Terraform. This workflow is ideal for initial experimentation with policy enforcement, but we do not recommend it for organizations with large numbers of policies. +- **Version control:** Connect HCP Terraform to a version control repository containing a policy set. When you push changes to the repository, HCP Terraform automatically uses the updated policy set. +- **Automated:** Push versions of policy sets to HCP Terraform with the [HCP Terraform Policy Sets API](/terraform/enterprise/api-docs/policy-sets#create-a-policy-set-version) or the `tfe` provider [`tfe_policy_set`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/policy_set) resource. This workflow is ideal for automated Continuous Integration and Deployment (CI/CD) pipelines. + +### Manage individual policies in the web UI + +You can add policies directly to HCP Terraform using the web UI. This process requires you to paste completed, valid Sentinel or Rego code into the UI. We recommend validating your policy code before adding it to HCP Terraform. + +#### Add managed policies + +To add an individually managed policy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to add policies to. +2. Choose **Settings** from the sidebar, then **Policies**. A list of managed policies in HCP Terraform appears. Each policy designates its policy framework (Sentinel or OPA) and associated policy sets. +3. Click **Create a new policy**. +4. Choose the **Policy framework** you want to use. You can only create a policy set from policies written using the same framework. You cannot change the framework type after you create the policy. +5. Complete the following fields to define the policy: + - **Policy Name:** Add a name containing letters, numbers, `-`, and `_`. HCP Terraform displays this name in the UI. The name must be unique within your organization. + - **Description:** Describe the policy’s purpose. The description supports Markdown rendering, and HCP Terraform displays this text in the UI. + - **Enforcement mode:** Choose whether this policy can stop Terraform runs and whether users can override it. Refer to [policy enforcement levels](#policy-enforcement-levels) for more details. + - **(OPA Only) Query:** Write a query to identify a specific policy rule within your rego code. HCP Terraform uses this query to determine the result of the policy. The query is typically a combination of the policy package name and rule name, such as `terraform.deny`. The result of this query must be an array. The policy passes when the array is empty. + - **Policy code**: Paste the code for the policy: either Sentinel code or Rego code for OPA policies. The UI provides syntax highlighting for the policy language. + - **(Optional) Policy sets:** Select one or more existing managed policy sets where you want to add the new policy. You can only select policy sets compatible with the chosen policy set framework. If there are no policy sets available, you can [create a new one](#create-policy-sets). + +The policy is now available in the HCP Terraform UI for you to edit and add to one or more policy sets. + +#### Edit managed policies + +To edit a managed policy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to edit policies for. +2. Choose **Settings** from the sidebar, then **Policies**. +3. Click the policy you want to edit to go to its details page. +4. Edit the policy's fields and then click **Update policy**. + +#### Delete managed policies + +~> **Warning:** Deleting a policy that applies to an active run causes that run’s policy evaluation stage to error. We recommend warning other members of your organization before you delete widely used policies. + +You can not restore policies after deletion. You must manually re-add them to HCP Terraform. You may want to save the policy code in a separate location before you delete the policy. + +To delete a managed policy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to delete a policy in. +2. Choose **Settings** from the sidebar, then **Policies**. +3. Click the policy you want to delete to go to its details page. +4. Click **Delete policy** and then click **Yes, delete policy** to confirm. + +The policy no longer appears in HCP Terraform and in any associated policy sets. + +## Manage policy sets + +Policy sets are collections of policies that you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. + +To view and manage policy sets, go to the **Policy Sets** section of your organization’s settings. This page contains all of the policy sets available in the organization, including those added through the API. + +The way you set up and configure a new policy set depends on your workflow and where you store policies. + +- For [managed policies](#managed-policies), you use the UI to create a policy set and add managed policies. +- For policy sets in a version control system, you use the UI to create a policy set connected to that repository. HCP Terraform automatically refreshes the policy set when you change relevant files in that repository. Version control policy sets have specific organization and formatting requirements. Refer to [Sentinel VCS Repositories](/terraform/enterprise/policy-enforcement/sentinel/vcs) and [OPA VCS Repositories](/terraform/enterprise/policy-enforcement/opa/vcs) for details. +- For automated workflows like continuous deployment, you can use the UI to create an empty policy set and then use the [Policy Sets API](/terraform/enterprise/api-docs/policy-sets) to add policies. You can also use the API or the [`tfe` provider (Sentinel Only)](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/policy_set) to add an entire, packaged policy set. + +### Create policy sets + +To create a policy set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to create a policy set in. + +2. Choose **Settings** from the sidebar, then **Policies**. + +3. Click **Connect a new policy set**. + +4. Choose your workflow. + - For managed policies, click **create a policy set with individually managed policies**. HCP Terraform shows a form to create a policy set and add individually managed policies. + - For version control policies, choose a version control provider and then select the repository with your policy set. HCP Terraform shows a form to create a policy set connected to that repository. + - For automated workflows, click **No VCS Connection**. HCP Terraform shows a form to create an empty policy set. You can use the API to add policies to this empty policy set later. + +5. Choose a **Policy framework** for the policies you want to add. A policy set can only contain policies that use the same framework (OPA or Sentinel). You cannot change a policy set's framework type after creation. + +6. Choose a policy set scope: + - **Policies enforced globally:** HCP Terraform automatically enforces this global policy set on all of an organization's existing and future workspaces. + - **Policies enforced on selected projects and workspaces:** Use the text fields to find and select the workspaces and projects to enforce this policy set on. This affects all current and future workspaces for any chosen projects. + +7. **(Optional)** Add **Policy exclusions** for this policy set. Specify any workspaces in the policy set's scope that HCP Terraform will not enforce this policy set on. + +8. **(Sentinel Only)** Choose a policy set type: + - **Standard:** This is the default workflow. A Sentinel policy set uses a [policy check](#policy-checks) in HCP Terraform and lets you access cost estimation data. + - **Agent:** A Sentinel policy set uses a [policy evaluation](#policy-evaluations) in HCP Terraform. This lets you enable policy overrides and enforce a Sentinel runtime version + +9. **(OPA Only)** Select a **Runtime version** for this policy set. + +10. **(OPA Only)** Allow **Overrides**, which enables users with override policy permissions to apply plans that have [mandatory policy](#policy-enforcement-levels) failures. + +11. **(VCS Only)** Optionally specify the **VCS branch** within your VCS repository where HCP Terraform should import new versions of policies. If you do not set this field, HCP Terraform uses your selected VCS repository's default branch. + +12. **(VCS Only)** Specify where your policy set files live using the **Policies path**. This lets you maintain multiple policy sets within a single repository. Use a relative path from your root directory to the directory that contains either the `sentinel.hcl` (Sentinel) or `policies.hcl` (OPA) configuration files. If you do not set this field, HCP Terraform uses the repository's root directory. + +13. **(Managed Policies Only)** Select managed **Policies** to add to the policy set. You can only add policies written with the same policy framework you selected for this set. + +14. Choose a descriptive and unique **Name** for the policy set. You can use any combination of letters, numbers, `-`, and `_`. + +15. Write an optional **Description** that tells other users about the purpose of the policy set and what it contains. + +### Edit policy sets + +To edit a policy set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to edit a policy set in. +2. Choose **Settings** from the sidebar, then **Policies**. +3. Click the policy set you want to edit to go to its settings page. +4. Adjust the settings and click **Update policy set**. + +### Evaluate a policy runtime upgrade + +You can validate that changing a policy runtime version does not introduce any breaking changes. + +To perform a policy evaluation: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. +2. Choose **Settings** from the sidebar, then **Policies** in your organization’s settings. +3. Click the policy set you want to upgrade. +4. Click the **Evaluate** tab. +5. Select the **Runtime version** you wish to upgrade to. +6. Select a **Workspace** to test the policy and upgraded version against. +7. Click **Evaluate**. + +HCP Terraform will execute the policy set using the specified version and the latest plan data for the selected workspace. It will display the evaluation results. If the evaluation returns a `Failed` status, inspect the JSON output to determine whether the issue is related to a non-compliant resource or is due to a syntax issue. +If the evaluation results in an error, check that the policy configuration is valid. + +### Delete policy sets + +~> **Warning:** Deleting a policy set that applies to an active run causes that run’s policy evaluation stage to error. We recommend warning other members of your organization before you delete widely used policy sets. + +You can not restore policy sets after deletion. You must manually re-add them to HCP Terraform. + +To delete a policy set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to delete a policy set in. +2. Choose **Settings** from the sidebar, then **Policies** in your organization’s settings. +3. Click the policy set you want to delete to go to its details page. +4. Click **Delete policy** and then click **Yes, delete policy set** to confirm. + +The policy set no longer appears on the UI and HCP Terraform no longer applies it to any workspaces. For managed policy sets, all of the individual policies are still available in HCP Terraform. You must delete each policy individually to remove it from your organization. + +### (Sentinel only) Sentinel parameters + +[Sentinel parameters](/sentinel/docs/language/parameters) are a list of key/value pairs that HCP Terraform sends to the Sentinel runtime when performing policy checks on workspaces. If the value parses as JSON, HCP Terraform sends it to Sentinel as the corresponding type (string, boolean, integer, map, or list). If the value fails JSON validation, HCP Terraform sends it as a string. + +You can set Sentinel parameters when you [edit a policy set](#edit-policy-sets). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/opa-vcs.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/opa-vcs.mdx new file mode 100644 index 0000000000..adb5027c99 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/opa-vcs.mdx @@ -0,0 +1,48 @@ +--- +page_title: Configure an OPA policy set with a VCS repository +description: Use a VCS repository to configure an OPA policy set in Terraform Enterprise. +source: terraform-docs-common +--- + +# Configure an OPA policy set with a VCS repository + +To enable policy enforcement, you must group OPA policies into policy sets and apply those policy sets globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. + +> **Hands-on:** Try the [Detect Infrastructure Drift and Enforce OPA Policies](/terraform/tutorials/cloud/drift-and-opa) tutorial. + +One way to create policy sets is by connecting HCP Terraform to a version control repository. When you push changes to the repository, HCP Terraform automatically uses the updated policy set. Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for more details. + +An OPA policy set repository contains a HashiCorp Configuration Language (HCL) configuration file and policy files. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Configuration File + +The root directory of your policy set repository must contain a configuration file named either `policies.hcl` or `policies.json`. Policy enforcement supports both HCL and the JSON variant of HCL syntax. +The configuration file contains one or more `policy` blocks that define each policy in the policy set. Unlike Sentinel, OPA policies do not need to be in separate files. You use an [OPA query](/terraform/enterprise/policy-enforcement/opa#opa-query) to identify each policy rule. + +The following example uses a query to define a policy named `policy1`. This query may evaluate across multiple files, or a single file. + +```hcl +policy "policy1" { + query = "data.terraform.policy1.deny" +} +``` + +Optionally, you can also provide a `description` and an `enforcement_level` property. If you do not specify an enforcement level, HCP Terraform uses `advisory`, meaning policy failures produce warnings but do not block Terraform runs. Refer to [Policy Enforcement Levels](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels) for more details. + +```hcl +policy "policy1" { + query = "data.terraform.policy1.deny" + enforcement_level = "mandatory" + description = "policy1 description" +} +``` + +## Policy Code Files + +All Rego policy files must end with `.rego` and exist in the local GitHub repository for the policy set. You can store them in separate directories from the configuration file. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs.mdx new file mode 100644 index 0000000000..3bb8a81579 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs.mdx @@ -0,0 +1,139 @@ +--- +page_title: Configure a Sentinel policy set with a VCS repository +description: >- + Use a VCS repository to configure a Sentinel policy set in Terraform + Enterprise. +source: terraform-docs-common +--- + +# Configure a Sentinel policy set with a VCS repository + +To enable policy enforcement, you must group Sentinel policies into policy sets. You can then apply those policy sets globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +One way to create policy sets is by connecting HCP Terraform to a version control repository. When you push changes to the repository, HCP Terraform automatically uses the updated policy set. Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for more details. + +A Sentinel policy set repository contains a Sentinel configuration file, policy files, and module files. + +## Configuration File + +Your repository must contain a configuration file named `sentinel.hcl` that defines the following features of the policy set: + +- Each policy included in the set. The policy name must match the names of individual [policy code files](#policy-code-files) exactly. HCP Terraform ignores policy files in the repository that are not listed in the configuration file. For each policy, the configuration file must designate the policy’s [enforcement level](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels) and [source](#policy-source). +- [Terraform modules](#modules) that policies in the set need to access. + +The following example shows a portion of a `sentinel.hcl` configuration file that defines a policy named `terraform-maintenance-windows`. The policy has a `hard-mandatory` enforcement level, meaning that it can block Terraform runs when it fails and users cannot override it. + +```hcl +policy "terraform-maintenance-windows" { + source = "./terraform-maintenance-windows.sentinel" + enforcement_level = "hard-mandatory" +} +``` + +To configure a module, add a `module` entry to your `sentinel.hcl` file. The following example adds a module called `timezone`. + +```hcl +module "timezone" { + source = "./modules/timezone.sentinel" +} +``` + +The repositories for [policy libraries on the Terraform Registry](https://registry.terraform.io/browse/policies) contain more examples. + +## Policy Code Files + +Define each Sentinel policy in a separate file within your repository. All local policy files must reside in the same directory as the `sentinel.hcl` configuration file and end with the `.sentinel` suffix. + +### Policy Source + +A policy's `source` field can either reference a file within the policy repository, or it can reference a remote source. For example, the configuration could reference a policy from HashiCorp's [foundational policies library](https://github.com/hashicorp/terraform-foundational-policies-library). Sentinel only supports HTTP and HTTPS remote sources. + +To specify a local source, prefix the `source` with a `./`, or `../`. The following example shows how to reference a local source policy called `terraform-maintenance-windows.sentinel`. + +```hcl +policy "terraform-maintenance-windows" { + source = "./terraform-maintenance-windows.sentinel" + enforcement_level = "hard-mandatory" +} +``` + +To specify a remote source, supply the URL as the `source`. The following example references a policy from HashiCorp's foundational policies library. + +```hcl +policy "deny-public-ssh-nsg-rules" { + source = "https://registry.terraform.io/v2/policies/hashicorp/azure-networking-terraform/1.0.2/policy/deny-public-ssh-nsg-rules.sentinel?checksum=sha256:75c95bf1d6eb48153cb31f15c49c237bf7829549beebe20effa07bcdd3f3cb74" + enforcement_level = "advisory" +} +``` + +For GitHub, you must use the URL of the raw policy content. Other URL types cause HCP Terraform to error when checking the policy. For example, do not use `https://github.com/hashicorp/policy-library-azure-networking-terraform/blob/main/policies/deny-public-ssh-nsg-rules/deny-public-ssh-nsg-rules.sentinel`. + +To access the raw URL, open the Sentinel file in your Github repository, right-click **Raw** on the top right of the page, and save the link address. + +### Example Policy + +The following example policy uses the `time` and `tfrun` imports and a custom `timezone` module to do the following tasks: + +1. Load the time when the Terraform run occurred +2. Convert the loaded time with the correct offset using the [Timezone API](https://timezoneapi.io/) +3. Verify that the provisioning operation occurs only on a specific day + +The example policy also uses a [rule expression](/sentinel/docs/language/spec#rule-expressions) with the `when` predicate. If the value of `tfrun.workspace.auto_apply` is false, the rule is not evaluated and returns true. + +Finally, the example uses parameters to facilitate module reuse within Terraform. Refer to the [Sentinel parameter documentation](/sentinel/docs/language/parameters) for details. + +```hcl +import "time" +import "tfrun" +import "timezone" + +param token default "WbNKULOBheqV" +param maintenance_days default ["Friday", "Saturday", "Sunday"] +param timezone_id default "America/Los_Angeles" + +tfrun_created_at = time.load(tfrun.created_at) + +supported_maintenance_day = rule when tfrun.workspace.auto_apply is true { + tfrun_created_at.add(time.hour * timezone.offset(timezone_id, token)).weekday_name in maintenance_days +} + +main = rule { + supported_maintenance_day +} +``` + +To expand the policy, you could use the [time.hour](/sentinel/docs/imports/time#time-hour) function to also restrict provisioning to specific times of day. + +## Modules + +HCP Terraform supports [Sentinel modules](/sentinel/docs/extending/modules). Modules let you write reusable policy code that you can import and use within several policies at once. + +You can store modules locally or retrieve them from a remote HTTP or HTTPS source. + +-> **Note:** We recommend reviewing [Sentinel runtime's modules documentation](/sentinel/docs/extending/modules) to learn how to use modules within Sentinel. However, the configuration examples in the runtime documentation are relevant to the Sentinel CLI and not HCP Terraform. + +The following example module loads the code at `./modules/timezone.sentinel` relative to the policy set working directory. Other modules can access this code with the statement `import "timezone"`. + +```hcl +import "http" +import "json" +import "decimal" + +httpGet = func(id, token){ + uri = "https://timezoneapi.io/api/timezone/?" + id + "&token=" + token + request = http.get(uri) + return json.unmarshal(request.body) +} + +offset = func(id, token) { + tz = httpGet(id, token) + offset = decimal.new(tz.data.datetime.offset_hours).int + return offset +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/prewritten-library.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/prewritten-library.mdx new file mode 100644 index 0000000000..fc023061da --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/prewritten-library.mdx @@ -0,0 +1,26 @@ +--- +page_title: Pre-written policy library +description: >- + HashiCorp authors and maintains a library of pre-written Sentinel policies + that enforce CIS and other compliance standards. Learn about the available + pre-written policies. +source: terraform-docs-common +--- + +# Pre-written policy library reference + +This topic provides reference information about the Sentinel policy libraries that HashiCorp authors and maintains. For instructions on how to run the policy libraries, refer to [Run pre-written Sentinel policies ](/terraform/enterprise/policy-enforcement/prewritten-sentinel). + +## Center for Internet Security (CIS) + +The Center for Internet Security (CIS) is a non-profit organization that publishes standards for configuring secure cloud services. Refer to the [CIS website](https://www.cisecurity.org) for additional information. + +HashiCorp publishes pre-written policies that support the following CIS benchmarks. + +### AWS + +- Amazon Web Services Foundations version 1.2. Refer to the [AWS documentation](https://docs.aws.amazon.com/securityhub/latest/userguide/cis-aws-foundations-benchmark.html#cis1v2-standard) for additional information about this version. +- Amazon Web Services Foundations version 1.4. Refer to the [AWS documentation](https://docs.aws.amazon.com/securityhub/latest/userguide/cis-aws-foundations-benchmark.html#cis1v4-standard) for additional information about this version. +- Amazon Web Services Foundations version 3.0. Refer to the [AWS documentation](https://docs.aws.amazon.com/securityhub/latest/userguide/cis-aws-foundations-benchmark.html#cis3v0-standard) for additional information about this version. + +Refer to the [CIS policy set for AWS GitHub repository](https://github.com/hashicorp/policy-library-CIS-Policy-Set-for-AWS-Terraform) for details about these policies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/prewritten-sentinel.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/prewritten-sentinel.mdx new file mode 100644 index 0000000000..ea73b949a1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/prewritten-sentinel.mdx @@ -0,0 +1,133 @@ +--- +page_title: Run pre-written Sentinel policies +description: >- + Learn how to download and install pre-written Sentinel policies created and + maintained by HashiCorp. +source: terraform-docs-common +--- + +# Run pre-written Sentinel policies + +This topic describes how to run Sentinel policies created and maintained by HashiCorp. For instructions about how to create your own custom Sentinel policies, refer to [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel). + +## Overview + +Pre-written Sentinel policy libraries streamline your compliance processes and enhance security across your infrastructure. HashiCorp's ready-to-use policies can help you enforce best practices and security standards across your AWS environment. + +Complete the following steps to implement pre-written Sentinel policies in your workspaces: + +1. Obtain the policies you want to implement. Download policies directly into your repository or create a fork of the HashiCorp repositories. Alternatively, you can add the Terraform module to your configuration, which acquires the policies and connects them to your workspaces in a single step. +2. Connect policies to your workspace. After you download policies or fork policy repositories, you must connect them to your HCP Terraform or Terraform Enterprise workspaces. + +Refer to the [Sentinel documentation](/sentinel/docs) for information about the Sentinel language. + +## Requirements + +You must use one of the following Terraform applications: + +- HCP Terraform +- Terraform Enterprise v202406-1 or newer + +### Permissions + +To create new policy sets and policies, your HCP Terraform or Terraform Enterprise user account must either be a member of the owners team or have the **Manage Policies** organization-level permissions enabled. Refer to the following topics for additional information: + +- [Organization owners](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) +- [Manage policies](/terraform/enterprise/users-teams-organizations/permissions#manage-policies) + +### Version control system + +You must have a GitHub account connected to HCP Terraform or Terraform Enterprise to manually connect policy sets to your workspaces. Refer to [Connecting VCS Providers](/terraform/enterprise/vcs) for instructions. + +## Get policies + +Refer to the [pre-written policy library reference](/terraform/enterprise/policy-enforcement/prewritten-library) for a complete list of available policy sets. You can also [browse the registry](https://registry.terraform.io/search/policies?q=Pre-written) to discover additional policy libraries. + +Use one of the following methods to get pre-written policies: + +- **Download policies from the registry**: Use this method if you want to assemble custom policy sets without customizing policies. +- **Fork the HashiCorp policy GitHub repository**: Use this method if you intend to customize the policies. +- **Add the Terraform module to your configuration**: Use this method to implement specific versions of the policies as-is. This method also connects the policies to workspaces in the Terraform configuration file instead of connecting them as a separate step. + + + + + +Complete the following steps to download policies from the registry and apply them directly to your workspaces. + +1. Browse the policy libraries available in the [Terraform registry](https://registry.terraform.io/search/policies?q=Pre-written). +2. Click on a policy library and click **Choose policies**. +3. Select the policies you want to implement. The registry generates code in the **USAGE INSTRUCTIONS** box. +4. Click **Copy Code Snippet** to copy the code to your clipboard. +5. Create a GitHub repository to store the policies and the policy set configuration file. +6. Create a file called `sentinel.hcl` in the repository. +7. Paste the code from your clipboard into `sentinel.hcl` and commit your changes. +8. Complete the instructions for [connecting the policies to your workspace](#connect-policies-to-your-workspace). + + + + +Create a fork of the repository containing the policies you want to implement. Refer to the [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) for instructions on how to create a fork. + +The following repositories are available: + +- [policy-library-CIS-Policy-Set-for-AWS-Terraform](https://github.com/hashicorp/policy-library-CIS-Policy-Set-for-AWS-Terraform) + +HashiCorp Sentinel policy libraries include a `sentinel.hcl` file. The file defines an example policy set using the policies included in the library. Modify the file to customize your policy set. Refer to [Sentinel Policy Set VCS Repositories](/terraform/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs) for additional information. + +After forking the repository, complete the instructions for [connecting the policies to your workspace](#connect-policies-to-your-workspace). + + + + +This method enables you to connect the policies to workspaces in the Terraform configuration file. As a result, you can skip the instructions described in [Connect policies to your workspaces](#connect-policies-to-your-workspaces). + +1. Go to the [module in the Terraform registry](https://registry.terraform.io/modules/hashicorp/CIS-Policy-Set/AWS/latest) and copy the code generated in the **Provision Instructions** tile. + +2. Add the `module` block to your Terraform configuration and define the following arguments: + + - `source`: Specify the path to the module you downloaded. + - `tfe_organization`: Specify the name of your organization on Terraform Enterprise or HCP Terraform. + - `policy_set_workspace_names`: Specify a list of workspace names that you want to apply the policies to. + + The following example configuration applies invokes the module for `target_workspace_1`: + + ```hcl + module "cis_v1-2-0_policies" { + source = "../prewritten-policy" + name = "cis-1-2-0" + tfe_organization = "" + policy_set_workspace_names = ["target_workspace_1"] + } + ``` + +3. Run `terraform plan` to view the plan. + +4. Run `terraform apply` to apply the changes. After running the command, Terraform will evaluate Sentinel policies for each following run of the workspaces you specified. + + + + +## Connect policies to your workspace + +Skip this step if you [added the Terraform module](#add-the-terraform-module-to-your-configuration) to your configuration. When you use the module, the `policy_set_workspace_names` argument instructs Terraform to connect the policies to the HCP Terraform workspaces specified in the configuration. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization with workspaces you want to connect policies to. +2. Choose **Settings** from the sidebar. +3. Click **Policy Sets** and click **Connect a new policy set**. +4. Click the **Version control provider (VCS)** tile. +5. Enable the **Sentinel** option as the policy framework. +6. Specify a name and description for the set. +7. Configure any additional options for the policy set and click **Next**. +8. Choose the GitHub connection type, then choose the repository you created in [Set up a repository for the policies](#set-up-a-repository-for-the-policies). +9. If the `sentinel.hcl` policy set file is stored in a subfolder, specify the path to the file in the **Policies path** field. The default is the root directory. +10. If you want to apply updated policy sets to the workspace from a specific branch, specify the name in the **VCS branch** field. The default is the default branch configured for the repository. +11. Click **Next** and specify any additional parameters you want to pass to the Sentinel runtime and click **Connect policy set** to finish applying the policies to the workspace. + +Run a plan in the workspace to trigger the connected policies. Refer to [Start a Terraform run](/terraform/enterprise/run/remote-operations#starting-runs) for additional information. + +## Next steps + +- Group your policies into sets and apply them to your workspaces. Refer to [Create policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets#create-policy-sets) for additional information. +- View results and address Terraform runs that do not comply with your policies. Refer to [View results](/terraform/enterprise/policy-enforcement/view-results) for additional information. +- You can also view Sentinel policy results in JSON format. Refer to [View Sentinel JSON results](/terraform/enterprise/policy-enforcement/view-results/json) for additional information. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/test-sentinel.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/test-sentinel.mdx new file mode 100644 index 0000000000..91be1391fe --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/test-sentinel.mdx @@ -0,0 +1,277 @@ +--- +page_title: Generate mock Sentinel data with Terraform Enterprise +description: >- + Learn how to generate mock Sentinel data to test your policies with Terraform + Enterprise. +source: terraform-docs-common +--- + +# Generate mock Sentinel data with Terraform + +We recommend that you test your Sentinel policies extensively before deploying +them within HCP Terraform. An important part of this process is mocking +the data that you wish your policies to operate on. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Due to the highly variable structure of data that can be produced by an +individual Terraform configuration, HCP Terraform provides the ability to +generate mock data from existing configurations. This can be used to create +sample data for a new policy, or data to reproduce issues in an existing one. + +Testing policies is done using the [Sentinel +CLI](/sentinel/docs/commands). More general information on +testing Sentinel policies can be found in the [Testing +section](/sentinel/docs/writing/testing) of the [Sentinel +runtime documentation](https://docs.hashicorp.com/sentinel). + +~> **Be careful!** Mock data generated by HCP Terraform directly exposes any +and all data within the configuration, plan, and state. Terraform attempts to +scrub sensitive data from these mocks, but we do not guarantee 100% accuracy. +Treat this data with care, and avoid generating mocks with live sensitive data +when possible. Access to this information requires [permission to download +Sentinel mocks](/terraform/enterprise/users-teams-organizations/permissions) for the +workspace where the data was generated. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Generating Mock Data Using the UI + +Mock data can be generated using the UI by expanding the plan status section of +the run page, and clicking on the **Download Sentinel mocks** button. + +![sentinel mock generate ui](/img/docs/download-mocks.png) + +For more information on creating a run, see the +[Terraform Runs and Remote Operations](/terraform/enterprise/run/remote-operations) section of the docs. + +If the button is not visible, then the plan is ineligible for mock generation or +the user doesn't have the necessary permissions. See [Mock Data +Availability](#mock-data-availability) for more details. + +## Generating Mock Data Using the API + +Mock data can also be created with the [Plan Export +API](/terraform/enterprise/api-docs/plan-exports). + +Multiple steps are required for mock generation. The export process is +asynchronous, so you must monitor the request to know when the data is generated +and available for download. + +1. Get the plan ID for the run that you want to generate the mock for by + [getting the run details](/terraform/enterprise/api-docs/run#get-run-details). + Look for the `id` of the `plan` object within the `relationships` section of + the return data. +2. [Request a plan + export](/terraform/enterprise/api-docs/plan-exports#create-a-plan-export) using the + discovered plan ID. Supply the Sentinel export type `sentinel-mock-bundle-v0`. +3. Monitor the export request by [viewing the plan + export](/terraform/enterprise/api-docs/plan-exports#show-a-plan-export). When the + status is `finished`, the data is ready for download. +4. Finally, [download the export + data](/terraform/enterprise/api-docs/plan-exports#download-exported-plan-data). + You have up to an hour from the completion of the export request - after + that, the mock data expires and must be re-generated. + +## Using Mock Data + +-> **Note:** The v2 mock files are only available on Terraform 0.12 and higher. + +Mock data is supplied as a bundled tarball, containing the following files: + + mock-tfconfig.sentinel # tfconfig mock data + mock-tfconfig-v2.sentinel # tfconfig/v2 mock data + mock-tfplan.sentinel # tfplan mock data + mock-tfplan-v2.sentinel # tfplan/v2 mock data + mock-tfstate.sentinel # tfstate mock data + mock-tfstate-v2.sentinel # tfstate/v2 mock data + mock-tfrun.sentinel # tfrun mock data + sentinel.hcl # sample configuration file + +The sample `sentinel.hcl` file contains mappings to the mocks so that you +can get started testing with `sentinel apply` right away. For `sentinel test`, +however, we recommend a more detailed layout. + +We recommend placing the files for `sentinel test` in a subdirectory +of the repository holding your policies, so they don't interfere with the +command's automatic policy detection. While the test data is Sentinel code, it's +not a policy and will produce errors if evaluated like one. + + . + ├── foo.sentinel + ├── sentinel.hcl + ├── test + │   └── foo + │   ├── fail.hcl + │   └── pass.hcl + └── testdata + ├── mock-tfconfig.sentinel + ├── mock-tfconfig-v2.sentinel + ├── mock-tfplan.sentinel + ├── mock-tfplan-v2.sentinel + ├── mock-tfstate.sentinel + ├── mock-tfstate-v2.sentinel + └── mock-tfrun.sentinel + +Each configuration that needs access to the mock should reference the mock data +files within the `mock` block in the Sentinel configuration file. + +For `sentinel apply`, this path is relative to the working directory. Assuming +you always run this command from the repository root, the `sentinel.hcl` +configuration file would look like: + +```hcl +mock "tfconfig" { + module { + source = "testdata/mock-tfconfig.sentinel" + } +} + +mock "tfconfig/v1" { + module { + source = "testdata/mock-tfconfig.sentinel" + } +} + +mock "tfconfig/v2" { + module { + source = "testdata/mock-tfconfig-v2.sentinel" + } +} + +mock "tfplan" { + module { + source = "testdata/mock-tfplan.sentinel" + } +} + +mock "tfplan/v1" { + module { + source = "testdata/mock-tfplan.sentinel" + } +} + +mock "tfplan/v2" { + module { + source = "testdata/mock-tfplan-v2.sentinel" + } +} + +mock "tfstate" { + module { + source = "testdata/mock-tfstate.sentinel" + } +} + +mock "tfstate/v1" { + module { + source = "testdata/mock-tfstate.sentinel" + } +} + +mock "tfstate/v2" { + module { + source = "testdata/mock-tfstate-v2.sentinel" + } +} + +mock "tfrun" { + module { + source = "testdata/mock-tfrun.sentinel" + } +} +``` + +For `sentinel test`, the paths are relative to the specific test configuration +file. For example, the contents of `pass.hcl`, asserting that the result of the +`main` rule was `true`, would be: + + mock "tfconfig" { + module { + source = "../../testdata/mock-tfconfig.sentinel" + } + } + + mock "tfconfig/v1" { + module { + source = "../../testdata/mock-tfconfig.sentinel" + } + } + + mock "tfconfig/v2" { + module { + source = "../../testdata/mock-tfconfig-v2.sentinel" + } + } + + mock "tfplan" { + module { + source = "../../testdata/mock-tfplan.sentinel" + } + } + + mock "tfplan/v1" { + module { + source = "../../testdata/mock-tfplan.sentinel" + } + } + + mock "tfplan/v2" { + module { + source = "../../testdata/mock-tfplan-v2.sentinel" + } + } + + mock "tfstate" { + module { + source = "../../testdata/mock-tfstate.sentinel" + } + } + + mock "tfstate/v1" { + module { + source = "../../testdata/mock-tfstate.sentinel" + } + } + + mock "tfstate/v2" { + module { + source = "../../testdata/mock-tfstate-v2.sentinel" + } + } + + mock "tfrun" { + module { + source = "../../testdata/mock-tfrun.sentinel" + } + } + + test { + rules = { + main = true + } + } + +## Mock Data Availability + +The following factors can prevent you from generating mock data: + +- You do not have permission to download Sentinel mocks for the workspace. + ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + Permission is required to protect the possibly sensitive data which can be + produced via mock generation. +- The run has not progressed past the planning stage, or did not create a plan + successfully. +- The run progressed past the planning stage prior to July 23, 2021. Prior to this date, HCP Terraform only kept JSON plans for 7 days. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If a plan cannot have its mock data exported due to any of these reasons, the +**Download Sentinel mocks** button within the plan status section of the UI will +not be visible. + +-> **Note:** Only a successful plan is required for mock generation. Sentinel can still generate the data if apply or policy checks fail. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/view-results/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/view-results/index.mdx new file mode 100644 index 0000000000..9c744110c5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/view-results/index.mdx @@ -0,0 +1,74 @@ +--- +page_title: View policy enforcement results in Terraform Enterprise +description: >- + Learn how to view and override policy enforcement results in Terraform + Enterprise. +source: terraform-docs-common +--- + +# View policy enforcement results + +When you add [policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) to a workspace, HCP Terraform enforces those policy sets on every Terraform run. HCP Terraform displays the policy enforcement results in the UI for each run. Depending on each policy’s [enforcement level](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels), policy failures can also stop the run and prevent Terraform from provisioning infrastructure. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Policy Evaluation Run Stages + +HCP Terraform only evaluates policies for successful plans. HCP Terraform evaluates Sentinel and OPA policy sets separately and at different points in the run. + +- Sentinel policy checks occur after Terraform completes the plan and after both [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) and [cost estimation](https://terraform.io/cloud-dodcs/cost-estimation). This order lets you write Sentinel policies to restrict costs based on the data in the cost estimates. +- Sentinel policy evaluations occur after Terraform completes the plan and after any run tasks. HCP Terraform evaluates Sentinel policy evaluations immediately before cost estimation. +- OPA policy evaluations occur after Terraform completes the plan and after any run tasks. HCP Terraform evaluates OPA policies immediately before cost estimation. + +Refer to [Run States and Stages](/terraform/enterprise/run/states) for more details. + +## View Policy Results + +To view the policy results for both Sentinel and OPA policies: + +1. Go to your workspace and navigate to the **Runs** page. +2. Click a run to view its details. + +HCP Terraform displays a timeline of the run’s events. For workspaces with both Sentinel and OPA policy sets, the run details page displays two separate run events: **OPA policies** for OPA policy sets and **Policy check** for Sentinel policy sets. + +Click a policy evaluation event to view policy results and details about any failed policies. + +-> **Note:** For Sentinel, the Terraform CLI also prints policy results for [CLI-driven runs](/terraform/enterprise/run/cli). CLI support for policy results is not available for OPA. + +## Override Policies + +You need [manage policy overrides](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) permissions to override failed Sentinel and OPA policies. + +Sentinel and OPA have different policy enforcement levels that determine when you need to override failed policies to allow a run to continue. +To override failed policies, go to the run details page and click **Override and Continue** at the bottom. + +For Sentinel only, you can also override `soft-mandatory` policies with the Terraform CLI. Run the `terraform apply` command and then enter `override` when prompted. + +-> **Note:** HCP Terraform does not allow policy overrides for [no-operation plans containing no infrastructure changes](/terraform/enterprise/run/modes-and-options#allow-empty-apply), unless you choose the **Allow empty apply** option when starting the run. + +### Sentinel + +#### Policy checks + +Policies with an `advisory` enforcement level never stop runs. If they fail, HCP Terraform displays a warning in the policy results and the run continues. + +You can override `soft-mandatory` policies to allow the run to continue. Overriding failed policies on a run does not affect policy evaluations on future runs in that workspace. + +You cannot override `hard-mandatory` policies, and all of these policies must pass for the run to continue. + +#### Policy evaluations + +Policies with an `advisory` enforcement level never stop runs. If they fail, HCP Terraform displays a warning in the policy results and the run continues. + +When running Sentinel policies as policy evaluations, `soft-mandatory` and `hard-mandatory` enforcement levels are internally converted to `mandatory` enforcement level. +You can override `mandatory` policies to allow the run to continue. + +### OPA + +Policies with an `advisory` enforcement level never stop runs. If they fail, HCP Terraform displays a warning in the policy results and the run continues. + +You can override `mandatory` policies to allow the run to continue. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/view-results/json.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/view-results/json.mdx new file mode 100644 index 0000000000..c0fa9f3707 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/policy-enforcement/view-results/json.mdx @@ -0,0 +1,59 @@ +--- +page_title: View and filter Sentinel JSON data +description: Learn how to view and filter Sentinel JSON data. +source: terraform-docs-common +--- + +# View and filter Sentinel JSON data + +When using the HCP Terraform UI, Sentinel policy check results are available +both in a human-readable log form, and in a more detailed, lower-level JSON +form. While the logs may suppress some output that would make the logs harder +to read, the JSON output exposes the lower-level output directly to you. Being +able to parse this data in its entirety is especially important when working +with [non-boolean rule +data](/sentinel/docs/language/rules#non-boolean-values) in +a policy designed to work with Sentinel 0.17.0 and higher. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +-> The JSON data exposed is the same as you would see when using the [policy +checks API](/terraform/enterprise/api-docs/policy-checks), with the data starting at the +`sentinel` key. + +## Viewing JSON Data + +To view the JSON data, expand the policy check on the [runs +page](/terraform/enterprise/run/manage) if it is not already expanded. The logs are +always displayed first, so click the **View JSON Data** button to view the JSON +data. You can click the **View Logs** button to switch back to the log view. + +![viewing json data](/img/docs/sentinel-view-json.png) + +## Filtering JSON Data + +The JSON data is filterable using a [jq](https://stedolan.github.io/jq/)-subset +filtering language. See the [JSON +filtering](/terraform/enterprise/workspaces/json-filtering) page for more details on +the filtering language. + +Filters are entered by putting the filter in the aptly named **filter** box in +the JSON viewer. After entering the filter, pressing **Apply** or the enter key +on your keyboard will apply the filter. The filtered results, if any, are +displayed in result box. Clearing the filter will restore the original JSON +data. + +![entering a json filter](/img/docs/sentinel-json-enter-filter.png) + +### Quick-Filtering `main` Rules + +Clicking the **Filter "main" rules** button will quickly apply a filter that +shows you the results of the `main` rule for every policy in the policy set. You +can use this to quickly get the results of each policy in the set, without +having navigate through the rest of the policy result data. + +![using the quick filter](/img/docs/sentinel-json-quick-filter.png) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/best-practices.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/best-practices.mdx new file mode 100644 index 0000000000..b1b60daf38 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/best-practices.mdx @@ -0,0 +1,40 @@ +--- +page_title: Best Practices - Projects - Terraform Enterprise +description: >- + Best practices to structure your configuration and Terraform Enterprise + projects +source: terraform-docs-common +--- + +# Project Best Practices + +Projects let you group and scope access to your workspaces. You can group related workspaces into projects and give teams more permissive access to individual projects rather than granting them permissions to the entire organization. + +Projects offer several advantages to help you further develop your workspace strategy: + +- **Focused workspace view**: You can scope which workspaces HCP Terraform displays by project, allowing for a more organized view. +- **Simplified workspace management**: You can create project-level permissions and variable sets that apply to all current and future workspaces in the project. For example, you can create a project variable set containing your cloud provider credentials for all workspaces in the project to access. +- **Reduced risk with centralized control**: You can scope project permissions to only grant teams administrator access to the projects and workspaces they need. + +## Recommendations + +When using projects, we recommend the following: + +- **Automate with Terraform**: Automate the creation of projects, variable sets, and teams together using the [TFE provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs). +- **Designate a landing zone project**: Landing zone projects contain workspaces used to create all other projects, teams, and workspaces. This lets you have a variable set that includes the organization token, which the TFE provider can use to create other resources in your organization. You can also create a [Sentinel policy](/terraform/enterprise/policy-enforcement) to prevent users in other projects from accessing the organization token. +- **Maintain least privilege**: Restrict the number of project administrators to maintain the principal of least privilege. + +## Project boundaries + +Finally, decide on the logical boundaries for your projects. Some considerations to keep in mind include: + +- **Provider boundaries**: For smaller organizations, creating one project per cloud account may make it easier to manage access. Projects can use [dynamic credentials](/terraform/tutorials/cloud/dynamic-credentials) by configuring a project variable set to avoid hard-coding long-lived static credentials. +- **Least privilege**: You can create teams and grant them access to projects with workspaces of similar areas of ownership. For example, a production networking workspace should be in a separate project from a development compute workspace. +- **Use variable sets**: Project-wide variable sets let you configure and reuse values such as default tags for cost-codes, owners, and support contacts. Projects can own variable sets, enabling you to separate management and access to sets between projects. +- **Practitioner efficiency**: Consider if it makes sense for a practitioner to need to visit multiple projects to complete a deployment. + +## Next steps + +This article introduces some considerations to keep in mind as your organization matures their project usage. Being deliberate about how you use these to organize your infrastructure will ensure smoother and safer operations. To learn more about HCP Terraform and Terraform Enterprise best practices, refer to [Workspace Best Practices](/terraform/enterprise/workspaces/best-practices). To learn best practices for writing Terraform configuration, refer to the [Terraform Style Guide](/terraform/language/style). + +[HCP Terraform](/terraform/tutorials/cloud-get-started) provides a place to try these concepts hands-on, and you can [get started for free](https://app.terraform.io/public/signup/account). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/index.mdx new file mode 100644 index 0000000000..62f7b9a260 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/index.mdx @@ -0,0 +1,51 @@ +--- +page_title: Projects - Terraform Enterprise +description: >- + Use projects to organize and group workspaces and create ownership boundaries + across your infrastructure. +source: terraform-docs-common +--- + +# Overview + + + +@include 'tfc-package-callouts/project-permissions.mdx' + + + +Projects let you organize your workspaces and scope access to workspace +resources. Each project has a separate permissions set that you can use to grant +teams access to all workspaces in the project, defining access control +boundaries for teams and their resources. Project-level permissions are more +granular than organization-level permissions, but more specific than individual +workspace-level grants. + +When deciding how to structure your projects, consider which groups of resources +need distinct access rules. You may wish to define projects by business units, +departments, subsidiaries, or technical teams. + +> **Hands On:** Try our [Managing +> Projects](/terraform/tutorials/cloud/projects) +> tutorial. + +## Default Project + +Every workspace must belong to exactly one project. By default, all workspaces +belong to an organization's **Default Project**. You can rename the default +project, but you cannot delete it. You can specify a workspace's project at the +time of creation and move it to a different project later. + +The “Manage Workspaces” team permission lets users create and manage workspaces. +Users with this permission can read and manage all workspaces, but new +workspaces are automatically added to the “Default Project” and users cannot +access the metadata for other projects. To create workspaces under other +projects, users also need the "Manage Projects & Workspaces" permission or the +admin role for the project they wish to use. + +## Managing Projects + +The "Manage all Projects" team permission lets users manage projects. Users with +this permission can view, edit, delete, and assign team access to all of an +organization's projects. Refer to [Managing +Projects](/terraform/enterprise/projects/manage) for more details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/manage.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/manage.mdx new file mode 100644 index 0000000000..3cc40daf60 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/projects/manage.mdx @@ -0,0 +1,122 @@ +--- +page_title: Manage projects in Terraform Enterprise +description: |- + Use projects to organize and group workspaces and create ownership boundaries + across your infrastructure. +source: terraform-docs-common +--- + +# Manage projects + +This topic describes how to create and manage projects in HCP Terraform and Terraform Enterprise. A project is a folder containing one or more workspaces. + +## Requirements + +You must have the following permissions to manage projects: + +- You must be a member of a team with the **Manage all Projects** permissions enabled to create a project. Refer to [Organization Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for additional information. +- You must be a member of a team with the **Visible** option enabled under **Visibility** in the organization settings to configure a new team's access to the project. Refer to [Team Visibility](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) for additional information. +- You must be a member of a team with update and delete permissions to be able to update and delete teams respectively. + +To delete tags on a project, you must be member of a team with the **Admin** permission group enabled for the project. + +To create tags for a project, you must be member of a team with the **Write** permission group enabled for the project. + +## View a project + +To view your organization's projects: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select **Projects** from the sidebar. +2. Search for a project that you want to view. You can use the following methods: + - Sort by column header. + - Use the search bar to search on the name of a project or a tag. +3. Click on a project's name to view more details. + +## Create a project + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select **Projects** from the sidebar. +2. Click **+ New project**. +3. Specify a name for the project. The name must be unique within the organization and can only include letters, numbers, inner spaces, hyphens, and underscores. +4. Add a description for the project. This field is optional. +5. Open the **Add key value tags** menu to add tags to your project. Workspaces you create within the project inherit project tags. Refer to [Define project tags](#define-project-tags) for additional information. +6. Click **+Add tag** and specify a tag key and tag value. If your organization has defined reserved tag keys, they appear in the **Tag key** field as suggestions. Refer to [Create and manage reserved tags](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for additional information. +7. Click **+ Add tag** to attach any additional tags. +8. Click **Create** to finish creating the project. + +HCP Terraform returns a new project page displaying all the project +information. + +## Edit a project + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select **Projects** from the sidebar. +2. Click on a project name of the project you want to edit. +3. Choose **Settings** from the sidebar. + +On this **General settings** page, you can update the project name, project +description, and delete the project. On the **Team access** page, you can modify +team access to the project. + +## Automatically destroy inactive workspaces + + + +@include 'tfc-package-callouts/ephemeral-workspaces.mdx' + + + +You can configure HCP Terraform to automatically destroy each workspace's +infrastructure in a project after a period of inactivity. A workspace +is _inactive_ if the workspace's state has not changed within your designated +time period. + +If you configure a project to auto-destroy its infrastructure when inactive, +any run that updates Terraform state further delays the scheduled auto-destroy +time by the length of your designated timeframe. + + +HCP Terraform and Terraform Enterprise do not prompt you to approve automated destroy plans. We recommend only using this setting for development environments. + + +To schedule an auto-destroy run after a period of workspace inactivity: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the project with workspaces you want to destroy. +2. Choose **Settings** from the sidebar, then **Auto-destroy Workspaces**. +3. Click **Set up default**. +4. Select or customize a desired timeframe of inactivity. +5. Click **Confirm default**. + +You can configure an individual workspace's auto-destroy settings to override +this default configuration. Refer to [automatically destroy workspaces](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy) for more information. + +## Delete a project + +You can only delete projects that do not contain stacks or workspaces. + +To delete an empty project: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Click **Projects**. +3. Search for a project that you want to review by scrolling down the table or + searching for a project name in the search bar above the project table. +4. Choose **Settings** from the sidebar. +5. Click the **Delete** button. A **Delete project** modal appears. +6. Click the **Delete** button to confirm the deletion. + +HCP Terraform returns to the **Projects** view with the deleted project +removed from the list. + +## Define project tags + +You can define tags stored as key-value pairs to help you organize your projects and track resource consumption. Workspaces created in the project automatically inherit the tags, but workspace administrators with appropriate permissions can attach new key-value pairs to their workspaces to override inherited tags. Refer to [Create workspace tags](/terraform/enterprise/workspaces/tags) for additional information about using tags in workspaces. + +The following rules apply to tag keys and values: + +- Tags must be one or more characters. +- Tags have a 255 character limit. +- Tags can include letters, numbers, colons, hyphens, and underscores. +- Tag values are optional. +- You can create up to 10 unique tags per workspace and 10 unique tags per project. As a result, each workspace can have up to 20 tags. +- You cannot use the following strings at the beginning of a tag key: + - `hcp` + - `hc` + - `ibm` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/add.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/add.mdx new file mode 100644 index 0000000000..72fbd0d5d4 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/add.mdx @@ -0,0 +1,79 @@ +--- +page_title: Add public providers and modules to the Terraform Enterprise private registry +description: >- + Learn how to add providers and modules from the public Terraform registry to + your organization's private registry. +source: terraform-docs-common +--- + +[vcs]: /terraform/enterprise/vcs + +# Add public providers and modules to the HCP Terraform private registry + +You can add providers and modules from the public [Terraform Registry](/terraform/registry) to your HCP Terraform private registry. The private registry stores a pointer to these public providers and modules so that you can view their data from within HCP Terraform. This lets you clearly designate which public providers and modules are recommended for the organization and makes their supporting documentation and examples centrally accessible. + +-> **Note:** Your Terraform Enterprise instance must allow access to `registry.terraform.io` and `https://yy0ffni7mf-dsn.algolia.net/`. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +You can add providers and modules through the UI as detailed below or through the [Registry Providers API](/terraform/enterprise/api-docs/private-registry/providers) and the [Registry Modules API](/terraform/enterprise/api-docs/private-registry/modules#create-a-module-with-no-vcs-connection-). + +## Permissions + +All members of an organization can view and use public providers and modules. Members of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) and teams with [Manage Private Registry permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) can add and delete them from the private registry. + +## Adding a Public Provider or Module + +> **Hands-on:** Try the [Add Public Providers and Modules to your Private Registry](/terraform/tutorials/modules/private-registry-add) tutorial and [Share Modules in the Private Registry](/terraform/tutorials/modules/module-private-registry-share) tutorials. + +To add a public provider or module: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to add a public provider or module to. + +2. Select **Registry** from the sidebar. The organization's private registry appears with a list of available providers and modules. + +3. Click **Search public registry**. The **Public Registry Search** page appears. + +4. Enter any combination of namespaces, such as `hashicorp`, and module or provider names into the search field. You can click **Providers** and **Modules** to toggle between lists of providers and modules that meet the search criteria. + +5. Do one of the following to add a provider or module to your private registry: + - Hover over the provider or module and click **+ Add**. + - Click the provider or module to view its details and then click **Add to HCP Terraform**. + +6. Click **Add to organization** in the dialog box. Members of your organization can now begin using it from the private registry. + +## Enabling and Disabling No-Code Provisioning + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +You can enable no-code provisioning for public modules after adding them to your registry. + +To support the auto-apply workflow, ensure that downstream users can automatically load provider credentials into their new no-code workspaces. You can enable access by either creating a [global or project-scoped variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) with the credentials for the module's provider, or by accessing outputs with credentials from other workspaces. Refer to [Provider Credentials](/terraform/enterprise/no-code-provisioning/module-design#provider-credentials) for more details. + +To enable no-code provisioning: + +1. Verify that the module meets the [requirements for no-code provisioning](/terraform/enterprise/no-code-provisioning/module-design#requirements). +2. Click the module to view its details. +3. Select **Enable no-code provisioning** from the **Manage Module for Organization** dropdown. + +Your module’s details page now has a **No-Code Ready** badge to indicate that it supports no-code provisioning. + +To disable no-code provisioning, select **Disable no-code provisioning** from the **Manage Module for Organization** dropdown. Disabling also removes the **No-Code Ready** badge from the module’s details page. + +## Removing a Public Provider or Module + +Removing a public provider or module from a private registry does not remove it from the public Terraform Registry. Users in the organization can still use the removed provider or module without changing their configurations. + +To remove a public provider or module from an organization's private registry: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization whose registry you want to remove a provider or module from. + +2. Select **Registry** from the sidebar. The organization's private registry appears with a list of available providers and modules. + +3. Select the provider or module to view its details, open the **Manage for Organization** menu, and click **Remove from organization** (providers) or **Delete module** (modules). + +4. Enter the provider or module name in the dialog box to confirm and then click **Remove** (providers) or **Delete** (modules). The provider or module no longer appears in the organization's private registry. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/airgapped-providers.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/airgapped-providers.mdx new file mode 100644 index 0000000000..99798d9e9b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/airgapped-providers.mdx @@ -0,0 +1,53 @@ +--- +page_title: Publish a public provider to an airgapped private registry +description: >- + Private registries in airgapped environments cannot access public providers. Learn how to publish an official public provider to an + airgapped private registry. +--- + +# Publish Public Providers to an Airgapped Private Registry + +This topic describes how to publish an official HashiCorp provider hosted in the public registry to a private registry in an airgapped environment. + +## Introduction + +Your Terraform Enterprise installation must be able to access the [public Terraform Registry](https://registry.terraform.io) to build workspaces that rely on official public HashiCorp providers. However, this is a problem if your Terraform Enterprise installation is in an airgapped environment without internet access. + +To solve this, you can download the public provider and [re-upload it to your private registry](/terraform/enterprise/registry/publish-providers). There are a few differences in the workflow for re-uploading a public HashiCorp provider. In this example, you will download the AWS provider and re-upload it to your private registry. You can use the same workflow for [any official HashiCorp provider](https://registry.terraform.io/browse/providers?tier=official). + +To re-upload a public HashiCorp provider to your private registry, complete the following steps. + +## Download required files + +Download the provider binary files for the provider, the `SHASUMS` file, and the `SHA256SUMS.72D7468F.sig` file. These files are available at [https://releases.hashicorp.com](https://releases.hashicorp.com). For this example, you can refer to the [AWS provider files](https://releases.hashicorp.com/terraform-provider-aws/5.14.0/) for more details. You will only re-upload the binaries for the `linux_amd64` architecture, but you can use this same process to re-upload multiple builds of the same provider. + +First, download the `SHASUMS` file. This file contains a SHA256 checksum for each build of this specific provider version. + +```shell-session +$ curl \ + https://releases.hashicorp.com/terraform-provider-aws/5.14.0/terraform-provider-aws_5.14.0_SHA256SUMS \ + --output terraform-provider-aws_5.14.0_SHA256SUMS +``` + +Next, download the `SHA256SUMS.72D7468F.sig` file. This file is a GPG binary signature of the `SHA256SUMS` file. + +```shell-session +$ curl \ + https://releases.hashicorp.com/terraform-provider-aws/5.14.0/terraform-provider-aws_5.14.0_SHA256SUMS.72D7468F.sig \ + --output terraform-provider-aws_5.14.0_SHA256SUMS.72D7468F.sig +``` + +Finally, download the `linux_amd64` build of the provider binary. + +```shell-session +$ curl \ + https://releases.hashicorp.com/terraform-provider-aws/5.14.0/terraform-provider-aws_5.14.0_linux_amd64.zip \ + --output terraform-provider-aws_5.14.0_linux_amd64.zip +``` + +## Create the provider + +Re-upload the provider by following the guide in [Publishing a provider](/terraform/enterprise/registry/publish-providers#publishing-a-provider). There are _two differences_ that you need to make in this workflow: + +- Do not sign the binary with your GPG key; [HashiCorp's public PGP key](https://www.hashicorp.com/.well-known/pgp-key.txt) has already signed it. +- Do not upload your public GPG key. Instead, use HashiCorp's public key. Terraform Enterprise version v202309-1 and newer includes the public key by default. The key ID is `34365D9472D7468F`. You can verify the ID by [importing the public key locally](/terraform/tutorials/cli/verify-archive#download-and-import-hashicorp-s-public-key). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/design.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/design.mdx new file mode 100644 index 0000000000..935081361e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/design.mdx @@ -0,0 +1,64 @@ +--- +page_title: Use the configuration designer in Terraform Enterprise +description: >- + Learn how to outline a configuration with private modules and define variables + with the Terraform Enterprise configuration designer. +source: terraform-docs-common +--- + +# Use the configuration designer + +HCP Terraform's private registry includes a configuration designer that can help you spend less time writing boilerplate code in a module-centric Terraform workflow. + +The configuration designer lets you outline a configuration for a new workspace by choosing any number of private modules. It then lists those modules' variables as a fillable HTML form, with a helper interface for finding values that you can interpolate. When you are finished, the designer returns the text of a `main.tf` configuration. This is the same Terraform code you would have written in your text editor. + +## Accessing the Configuration Designer + +Go to your organization's private registry, and then click **<> Design Configuration**. + +The **Select Modules** page appears. + +## Adding Modules + +Filter and search the left side of the **Select Modules** page to find private modules that you can add to your configuration. + +Click **Add Module** for all of the modules you want to use in your configuration. These modules appear in the **Selected Modules** list on the right side of the page. + +### Setting Versions + +Selecting a module adds its most recent version to the configuration. To specify a different version: + +1. Click the module's version number from the **Selected Modules** list on the right. +2. Select an alternate version from the menu. + +## Setting Variables + +When you finish selecting modules, click **Next »** to go to the **Set Variables** page. + +The left side of this page lists your chosen modules, and the right side lists all variables for the currently selected module. Each variable is labeled as required or optional. + +You can switch between modules without losing your work; click a module's **Configure** button to switch to its variable list. + +Once you set a value for all of a module's required variables, its **Configure** button changes to a green **Configured** button. + +### Interpolation Searching + +Variable values can be literal strings, or can interpolate other values. When you start typing an interpolation token (`${`), the designer displays a help message. As you continue typing, it searches the available outputs in your other selected modules, as well as outputs from workspaces where you are authorized to read state outputs. You can select one of these search results, or type a full name if you need to reference a value HCP Terraform does not know about. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Deferring Variables + +Sometimes, configuration users should be able to set certain variables according to their use cases. + +Select the **Deferred** checkbox to delegate a variable to configuration users. This ties the variable's value to a new top-level Terraform variable with no default value. All users that create a workspace from your configuration will have to provide a value for that variable. + +## The Output Configuration + +When all modules are configured, click **Next »**. + +The **Publish** page appears. Use the **Preview configuration** menu to review the generated code. + +The configuration designer does not create any repositories or workspaces. To create workspaces with the configuration, you must download the generated code, save it as the `main.tf` file in a new directory, and commit it to version control. After you download the code, you can make any necessary changes or additions. For example, you may want to add non-module resources. + +When you are sure you have downloaded the results, click **Done** to discard the configuration. HCP Terraform does not save output from previous configuration designer runs. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/index.mdx new file mode 100644 index 0000000000..0405c24452 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/index.mdx @@ -0,0 +1,27 @@ +--- +page_title: Terraform Enterprise private registry overview +description: >- + The Terraform Enterprise private registry lets you share private modules and + providers across your organization. +source: terraform-docs-common +--- + +# HCP Terraform private registry overview + +HCP Terraform's private registry works similarly to the [public Terraform Registry](/terraform/registry) and helps you share [Terraform providers](/terraform/language/providers) and [Terraform modules](/terraform/language/modules) across your organization. It includes support for versioning and a searchable list of available providers and modules. + +> **Hands-on:** Try the [Add Public Providers and Modules to your Private Registry](/terraform/tutorials/modules/private-registry-add) tutorial and [Share Modules in the Private Registry](/terraform/tutorials/modules/module-private-registry-share) tutorials. + +## Public Providers and Modules + +[Public modules and providers](/terraform/enterprise/registry/add) are hosted on the public Terraform Registry and HCP Terraform can automatically synchronize them to an organization's private registry. This lets you clearly designate which public providers and modules are recommended for the organization and makes their supporting documentation and examples centrally accessible. + +-> **Note:** Your Terraform Enterprise instance must allow access to `registry.terraform.io` and `https://yy0ffni7mf-dsn.algolia.net/`. + +## Private Providers and Modules + +[Private providers](/terraform/enterprise/registry/publish-providers) and [private modules](/terraform/enterprise/registry/publish-modules) are hosted on an organization's private registry and are only available to members of that organization. In Terraform Enterprise, private providers and modules are also available to other organizations that are [configured to share](/terraform/enterprise/admin/application/registry-sharing) with that organization. + +## Managing Usage + +You can create [Sentinel policies](/terraform/enterprise/policy-enforcement) to manage how members of your organization can use modules from the private registry. For example, you can mandate that all non-root modules in Terraform configurations must be private or public modules from your own private registry. You can also apply a policy that requires all modules to use recent versions. Refer to our [example policy on GitHub](https://github.com/hashicorp/terraform-sentinel-policies/blob/main/cloud-agnostic/http-examples/use-recent-versions-from-pmr.sentinel). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/manage-module-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/manage-module-versions.mdx new file mode 100644 index 0000000000..e43344db22 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/manage-module-versions.mdx @@ -0,0 +1,82 @@ +--- +page_title: Deprecate module versions in Terraform Enterprise +description: >- + Learn how to deprecate a module version and revert a module version’s + deprecation. Deprecating a module version allows you to warn users of that + version’s end of life, enabling consumers to upgrade their modules when it’s + convenient and without disrupting their workflows. +source: terraform-docs-common +--- + +# Deprecate module versions + +Deprecating a module version in your organization’s private registry adds warnings to the module's registry page and warnings in the run outputs of any users of that version. Once you have deprecated a module version, you can revert it back to remove the warnings from that version. + + + +@include "tfc-package-callouts/manage-module-versions.mdx" + + + +You can also [deprecate module versions using the HCP Terraform API](/terraform/enterprise/api-docs/private-registry/manage-module-versions). + +## Background + +Deprecating a module version allows platform teams and module authors to mark the end-of-life for specific private module versions. Deprecating module versions helps consumers recognize versions that are still maintained and supported but not recommended. + +You can deprecate a private module version to warn existing users to upgrade that version in their configuration. The private registry also denotes which module versions are deprecated, alerting new consumers that they should use a non-deprecated version instead. + +## Requirements + +To deprecate a module version or to revert a version’s deprecation: + +- you must have permission to manage [private registry modules](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#manage-private-registry) +- the module must be in the [private](https://developer.hashicorp.com/terraform/cloud-docs/registry/publish-modules) registry + +## Deprecate a module version + +To deprecate a module version, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. +2. Choose **Registry** in the sidebar to navigate to your organization’s private registry, then find the module you want to deprecate a version of. +3. Open the **Manage module for organization** dropdown. +4. Select a module version for deprecation. +5. You can optionally provide an explanation in the **Reason for module deprecation** field to help users understand why this module version is being deprecated. This custom message is displayed to module users in deprecation warnings. +6. You can optionally enter a URL into the **Link to additional information** field if there is a website where consumers can learn more about that module version’s deprecation. +7. Click **Deprecate**. + +If the module version you are deprecating has the [**No-code ready**](/terraform/enterprise/no-code-provisioning/module-design#updating-a-module-s-version) pin, then HCP Terraform lets you select another version to create no-code modules from. We recommend adding the **No-code ready** pin to another non-deprecated module version so that users provisioning workspaces from your module can use a version that you plan to continue supporting. + +### Deprecation warnings + +After you deprecate a module version, consumers of that version receive warnings in their operation outputs urging them to update that version in both HCP Terraform and the Terraform CLI. + +~> **Note**: Only workspaces in the [remote or agent execution modes](/terraform/enterprise/workspaces/settings#execution-mode) can receive warnings for a module version’s deprecation. + +If you provided a reason for a module version’s deprecation, then the warning users receive contains that reason and the following message: + +```shell +Found the following deprecated module versions, consider using an updated version. + +``` + +A run’s output mode affects where a module deprecation’s warning appears. If a run set to the default [**Structured Run Output**](/terraform/enterprise/workspaces/settings#user-interface) mode, then module deprecation warnings show up under a run’s Diagnostics dropdown. + +If a run is in the **Console UI** mode, module deprecation warnings appear in the run’s logs: + +```shell +Warning: Deprecated modules found, consider installing an updating version. The following are affected: +Version X.X.X of +``` + +## Revert the deprecation of a module version + +To revert a module version’s deprecation, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. +2. Choose **Registry** in the sidebar to navigate to your organization’s private registry, then find the deprecated module version you want to revert the deprecation of. +3. Open the **Manage module for organization** dropdown. +4. Select **Revert module version deprecation X.X.X**. +5. Click **Revert Deprecation**. + +Reverting the deprecation of a module version removes all warnings from that version in both the module’s registry page and in the run outputs of that module version’s consumers. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/publish-modules.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/publish-modules.mdx new file mode 100644 index 0000000000..657f740572 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/publish-modules.mdx @@ -0,0 +1,165 @@ +--- +page_title: Publish private modules to the Terraform Enterprise private registry +description: >- + Use the Terraform Enterprise private registry to publish and share private + modules across your organization. +source: terraform-docs-common +--- + +[vcs]: /terraform/enterprise/vcs + +# Publish private modules to the HCP Terraform private registry + +> **Hands-on:** Try the [Share Modules in the Private Module Registry](/terraform/tutorials/modules/module-private-registry-share) tutorial. + +In addition to [adding modules from the Terraform Registry](/terraform/enterprise/registry/add), you can publish private modules to an organization's HCP Terraform private registry. The registry handles downloads and controls access with HCP Terraform API tokens, so consumers do not need access to the module's source repository, even when running Terraform from the command line. + +The private registry uses your configured [Version Control System (VCS) integrations][vcs] and defers to your VCS provider for most management tasks. For example, your VCS provider handles new version releases. The only manual tasks are adding a new module and deleting module versions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Permissions + +Private modules are only available to members of the organization where you add them. In Terraform Enterprise, they are also available to organizations that you configure to [share modules](/terraform/enterprise/admin/application/registry-sharing) with that organization. + +Members of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) and teams with [Manage Private Registry permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) can publish and delete modules from the private registry. + +## Preparing a Module Repository + +After you configure at least one [connection to a VCS provider][vcs], you can publish a new module by specifying a properly formatted VCS repository (details below). The registry automatically detects the rest of the information it needs, including the module's name and its available versions. + +A module repository must meet all of the following requirements before you can add it to the registry: + +- **Location and permissions:** The repository must be in one of + your configured [VCS providers][vcs], and HCP Terraform's VCS user account must have admin access to the repository. The registry needs admin access to create the webhooks to import new module versions. GitLab repositories must be in the main organization or group, and not in any subgroups. + +- **Named `terraform--`:** Module repositories must use this + three-part name format, where `` reflects the type of infrastructure + the module manages and `` is the main provider where it creates that + infrastructure. The `` segment must be all lowercase. The `` + segment can contain additional hyphens. Examples: `terraform-google-vault` or + `terraform-aws-ec2-instance`. + +- **Standard module structure:** The module must adhere to the + [standard module structure](/terraform/language/modules/develop/structure). + This allows the registry to inspect your module and generate documentation, + track resource usage, and more. + +## Publishing a New Module + +You can publish modules through the UI as shown below or with the [Registry Modules API](/terraform/enterprise/api-docs/private-registry/modules). The API also supports publishing modules without a VCS repo as the source, which is not possible in the UI. + +To publish a new module: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to publish a module. + +2. Select **Registry** from the sidebar. + +3. Click **Publish** and select **Module**. + + The **Add Module** page appears with a list of available repositories. + +4. Select the repository containing the module you want to publish. + + You can search the list by typing part or all of a repository name into the filter field. Remember that VCS providers use `/` strings to locate repositories. The namespace is an organization name for most providers, but Bitbucket Data Center, not Bitbucket Cloud, uses project keys, like `INFRA`. + +5. When prompted, choose either the **Tag** or **Branch** module publishing type. + +6. (Optional) If this module is a [no-code ready module](/terraform/enterprise/no-code-provisioning/module-design), select the **Add Module to no-code provision allowlist** checkbox. + +7. Click **Publish module**. + + HCP Terraform displays a loading page while it imports the module versions and then takes you to the new module's details page. On the details page, you can view available versions, read documentation, and copy a usage example. + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +### Tag-based publishing considerations + +When using the **Tag** module publishing type, the registry uses `x.y.z` formatted release tags to identify module versions. Your repository must contain at least one release tag for you to publish a module. Release tag names must be a [semantic version](http://semver.org), which you can optionally prefix with a `v`. For example, `v1.0.4` and `0.9.2`. The registry ignores tags that do not match these formats. + + + +### Branch-based publishing considerations + +When using the **Branch** module publishing type, you must provide the name of an existing branch in your VCS repository and give the module a **Module version**. Your VCS repository does not need to contain a matching tag or release. + +You can only enable testing on modules published using branch-based publishing. Refer to the [test-integrated modules](/terraform/enterprise/registry/test) documentation for more information. + + + +## Releasing New Versions of a Module + + + +The process to release a new module version differs between the tag-based and branch-based publishing workflows. + +### Tag-Based Publishing Workflow + + + +To release a new version of a module in the tag-based publishing workflow, push a new release tag to its VCS repository. The registry automatically imports the new version. + +Refer to [Preparing a Module Repository](#preparing-a-module-repository) for details about release tag requirements. + + + +### Branch-Based Publishing Workflow + +To release a new version of a module using the branch-based publishing workflow, navigate to the module overview screen, then click the **Publish New Version** button. Select the commit SHA that the new version will point to, and assign a new module version. You cannot re-use an existing module version. + +## Update Publish Settings + +After publishing your module, you can change between tag-based and branch-based publishing. To update your module's publish settings, navigate to the the module overview page, click the **Manage Module for Organization** dropdown, and then click **Publish Settings**. + +- To change from tag-based to branch-based publishing, you must configure a **Module branch** and [create a new module version](#branch-based-publishing-workflow), as HCP Terraform will not automatically create one. + +- To change from branch-based publishing to tag-based publishing, you must create at least one tag in your VCS repository. + + + +## Deleting Versions and Modules + +-> **Note:** Deleting a tag from your VCS repository does not automatically remove the version from the private registry. + +You can delete individual versions of a module or the entire module. If deleting a module version would leave a module with no versions, HCP Terraform removes the entire module. To delete a module or version: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the module's details page. + +2. If you want to delete a single version, use the **Versions** menu to select it. + +3. Click **Delete module**. + +4. Select an action from the menu: + + - **Delete only this module version:** Deletes only the version of the module you were viewing when you clicked **Delete module**. + - **Delete all versions for this provider for this module:** Deletes the entire module for a single provider. This action is important if you have modules with the same name but with different providers. For example, if you have module repos named `terraform-aws-appserver` and `terraform-azure-appserver`, the registry treats them as alternate providers of the same `appserver` module. + - **Delete all providers and versions for this module:** Deletes all modules with this name, even if they are from different providers. For example, this action deletes both `terraform-aws-appserver` and `terraform-azure-appserver`. + +5. Type the module name and click **Delete**. + +### Restoring a Deleted Module or Version + +Deletion is permanent, but there are ways to restore deleted modules and module versions. + +- To restore a deleted module, re-add it as a new module. +- To restore a deleted version, either delete the corresponding tag from your VCS and push a new tag with the same name, or delete the entire module from the registry and re-add it. + +## Sharing Modules Across Organizations + +HCP Terraform does not typically allow one organization's workspaces to use private modules from a different organization. This restriction is because HCP Terraform gives Terraform temporary credentials to access modules that are only valid for that workspace's organization. Although it is possible to mix modules from multiple organizations when you run Terraform on the command line, we strongly recommend against it. + +Instead, you can share modules across organizations by sharing the underlying VCS repository. Grant each organization access to the module's repository, and then add the module to each organization's registry. When you push tags to publish new module versions, both organizations update accordingly. + +Terraform Enterprise administrators can configure [module sharing](/terraform/enterprise/admin/application/registry-sharing) to allow organizations to use private modules from other organizations. + +## Generating Module Tests (Beta) + +You can generate and run generated tests for your module with [the `terraform test` command](/terraform/cli/commands/test). + +Before you can generate tests for a module, it must have at least one version published. Tests can only be generated once per module and are intended to be reviewed by the module's authors before being checked into version control and maintained with the rest of the module's content. If the module's configuration files exceed 128KB in total size, HCP Terraform will not be able to generate tests for that module. + +You must have [permission to manage registry modules](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) and [permission to manage module test generation](/terraform/enterprise/users-teams-organizations/permissions#manage-module-test-generation-beta) to generate tests. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/publish-providers.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/publish-providers.mdx new file mode 100644 index 0000000000..a7a1d6f811 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/publish-providers.mdx @@ -0,0 +1,266 @@ +--- +page_title: Publish private providers to the Terraform Enterprise private registry +description: >- + Use the Terraform Enterprise private registry to publish and share private + providers across your organization. +source: terraform-docs-common +--- + +# Publish private providers to the HCP Terraform private registry + +In addition to [curating public providers from the Terraform Registry](/terraform/enterprise/registry/add), you can publish private providers to an organization's HCP Terraform private registry. Once you have published a private provider through the API, members of your organization can search for it in the private registry UI and use it in configurations. + +## Requirements + +Review the following before publishing a new provider or provider version. + +### Permissions + +Users must be members of an organization to access its registry and private providers. In Terraform Enterprise, providers are also available to organizations that you configure to [share registry access](/terraform/enterprise/admin/application/registry-sharing). + +You must be a member of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or a team with [Manage Private Registry permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) to publish and delete private providers from the private registry. + +### Release files + +You must publish at least one version of your provider that follows [semantic versioning format](http://semver.org). For each version, you must upload the `SHA256SUMS` file, `SHA256SUMS.sig` file, and one or more provider binaries. Using GoReleaser to [create a release on GitHub](/terraform/registry/providers/publishing#creating-a-github-release) or [create a release locally](/terraform/registry/providers/publishing#using-goreleaser-locally) generates these files automatically. The private registry does not have strict naming conventions, but we recommend using GoReleaser file naming schemes for consistency. + +Private providers do not currently support documentation. + +### Signed releases + +GPG signing is required for private providers, and you must upload the public key of the GPG keypair used to sign the release. Refer to [Preparing and Adding a Signing Key](/terraform/registry/providers/publishing#preparing-and-adding-a-signing-key) for more details. Unlike the public Terraform Registry, the private registry does not automatically upload new releases. You must manually add new provider versions and the associated release files. + +-> **Note**: If you are using the [provider API](/terraform/enterprise/api-docs/private-registry/providers) to upload an official HashiCorp public provider into your private registry, use [HashiCorp's public PGP key](https://www.hashicorp.com/.well-known/pgp-key.txt). You do not need to upload this public key, and it is automatically included in Terraform Enterprise version v202309-1 and newer. + +## Publishing a provider + +Before consumers can use a private provider, you must do the following: + +1. [Create the provider](#create-the-provider) +2. [Upload a GPG signing key](#add-your-public-key) +3. [Create at least one version](#create-a-version) +4. [Create at least one platform for that version](#create-a-provider-platform) +5. [Upload release files](#upload-provider-binary) + +### Create the provider + +Create a file named `provider.json` with the following contents. Replace `PROVIDER_NAME` with the name of your provider and replace `ORG_NAME` with the name of your organization. + +```json +{ + "data": { + "type": "registry-providers", + "attributes": { + "name": "PROVIDER_NAME", + "namespace": "ORG_NAME", + "registry-name": "private" + } + } +} +``` + +Use the [Create a Provider endpoint](/terraform/enterprise/api-docs/private-registry/providers#create-a-provider) to create the provider in HCP Terraform. Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token and replace `ORG_NAME` with the name of your organization. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @provider.json \ + https://app.terraform.io/api/v2/organizations/ORG_NAME/registry-providers +``` + +The provider is now available in your organization’s HCP Terraform private registry, but consumers cannot use it until you add a version and a platform. + +To create a version and a platform, you need the following resources: + +- The Provider binaries +- A public GPG signing key +- A `SHA256SUMS` file +- A `SHA256SUMS.sig` file from at least one release + +### Add your public key + +-> **Note**: If you are uploading an official HashiCorp public provider into your private registry, skip this step and instead use [HashiCorp's public PGP key](https://www.hashicorp.com/.well-known/pgp-key.txt) in the the [create a version](#create-a-version) step. The key ID for HashiCorp's public ID is `34365D9472D7468F`, and you can verify the ID by [importing the public key locally](/terraform/tutorials/cli/verify-archive#download-and-import-hashicorp-s-public-key). + +Create a file named `key.json` with the following contents. Replace `ORG_NAME` with the name of your organization, and input your public key in an RSA or DSA format in the `ascii-armor` field. + +```hcl +{ + "data": { + "type": "gpg-keys", + "attributes": { + "namespace": "ORG_NAME", + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n" + } } +} +``` + +Use the [Add a GPG key endpoint](/terraform/enterprise/api-docs/private-registry/gpg-keys#add-a-gpg-key) to add the public key that matches the signing key for the release. Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @key.json \ + https://app.terraform.io/api/registry/private/v2/gpg-keys +``` + +The response contains a `key-id` that you will use to create a provider version. + +```json +"key-id": "34365D9472D7468F" +``` + +### Create a version + +Create a file named `version.json` with the following contents. Replace the value of the `version` field with the version of your provider, and replace the `key-id` field with the id of the GPG key that you created in the [Add your public key](#add-your-public-key) step. If you are uploading an official HashiCorp public provider, use the value `34365D9472D7468F` for your `key-id`. + +```hcl +{ + "data": { + "type": "registry-provider-versions", + "attributes": { + "version": "5.14.0", + "key-id": "34365D9472D7468F", + "protocols": ["5.0"] + } + } +} +``` + +Use the [Create a Provider Version endpoint](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-version) to create a version for your provider. Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token, and replace both instances of `ORG_NAME` with the name of your organization. If are not using the `aws` provider, then replace `aws` with your provider's name. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @version.json \ + https://app.terraform.io/api/v2/organizations/ORG_NAME/registry-providers/private/ORG_NAME/aws/versions +``` + + The response includes URL links that you will use to upload the `SHA256SUMS` and `SHA256.sig` files. + +```json +"links": { + "shasums-upload": "https://archivist.terraform.io/v1/object/dmF1b64hd73ghd63", + "shasums-sig-upload": "https://archivist.terraform.io/v1/object/dmF1b37dj37dh33d" + } +``` + +### Upload signatures + +Upload the `SHA256SUMS` and `SHA256SUMS.sig` files to the URLs [returned in the previous step](#create-a-version). The example command below uploads the files from your local machine. First upload the `SHA256SUMS` file to the URL returned in the `shasums-upload` field. + +```shell-session +$ curl \ + -T terraform-provider-aws_5.14.0_SHA256SUMS \ + https://archivist.terraform.io/v1/object/dmF1b64hd73ghd63... +``` + +Next, upload the `SHA256SUMS.sig` file to the URL returned in the `shasums-sig-upload` field. + +```shell-session +$ curl \ + -T terraform-provider-aws_5.14.0_SHA256SUMS.72D7468F.sig \ + https://archivist.terraform.io/v1/object/dmF1b37dj37dh33d... +``` + +### Create a provider platform + +First, calculate the SHA256 hash of the provider binary that you intend to upload. This should match the SHA256 hash of the file listed in the `SHA256SUMS` file. + +```shell-session +$ shasum -a 256 terraform-provider-aws_5.14.0_linux_amd64.zip +f1d83b3e5a29bae471f9841a4e0153eac5bccedbdece369e2f6186e9044db64e terraform-provider-aws_5.14.0_linux_amd64.zip +``` + +Next, create a file named `platform.json`. Replace the `os`, `arch`, `filename`, and `shasum` fields with the values that match the provider you intend to upload. + +```json +{ + "data": { + "type": "registry-provider-version-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "shasum": "f1d83b3e5a29bae471f9841a4e0153eac5bccedbdece369e2f6186e9044db64e", + "filename": "terraform-provider-aws_5.14.0_linux_amd64.zip" + } + } +} +``` + +Use the [Create a Provider Platform endpoint](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-platform) to create a platform for the version. Platforms are binaries that allow the provider to run on a particular operating system and architecture combination (e.g., Linux and AMD64). Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token and replace both instances of `ORG_NAME` with the name of your organization. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @platform.json \ + https://app.terraform.io/api/v2/organizations/ORG_NAME/registry-providers/private/ORG_NAME/aws/versions/5.14.0/platforms +``` + +The response includes a `provider-binary-upload` URL that you will use to upload the binary file for the platform. + +```json +"links": { + "provider-binary-upload": "https://archivist.terraform.io/v1/object/dmF1b45c367djh45nj78" + } +``` + +### Upload provider binary + +Upload the platform binary file to the `provider-binary-upload` URL returned in the [previous step](#create-a-version). The example command below uploads the binary from your local machine. + +```shell-session +$ curl -T local-example/terraform-provider-random_5.14.0_linux_amd64.zip + https://archivist.terraform.io/v1/object/dmF1b45c367djh45nj78 +``` + +The version is available in the HCP Terraform user interface. Consumers can now begin using this provider version in configurations. You can repeat these steps starting from [Create a provider platform](#create-a-provider-platform) to add additional platform binaries for the release. + +## Checking Release Files + +Consumers cannot use a private provider version until you upload all required [release files](#release-files). To determine whether these files have been uploaded: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to publish a private provider. +2. Click **Registry** and click the private provider to go to its details page. +3. Use the version menu to navigate to the version you want to check. The UI shows a warning banner for versions that do not have all required release files. +4. Open the **Manage Provider** menu and select **Show release files**. The **Release Files** page appears containing lists of uploaded and missing files for the current version. + +## Managing private providers + +Use the HCP Terraform API to create, read, update, and delete the following: + +- [GPG keys](/terraform/enterprise/api-docs/private-registry/gpg-keys) +- [Private providers](/terraform/enterprise/api-docs/private-registry/providers) +- [Provider versions and platforms](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms) + +## Deleting private providers and versions + +In addition to the [Registry Providers API](/terraform/enterprise/api-docs/private-registry/providers#delete-a-provider), you can delete providers and provider versions through the HCP Terraform UI. To delete providers and versions in the UI: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization whose private registry you want to delete a provider or provider version from. + +2. Click **Registry** and click the private provider to go to its details page. + +3. If you want to delete a single version, use the **Versions** menu to select it. + +4. Open the **Manage Provider** menu and select **Delete Provider**. The **Delete Provider from Organization** box appears. + +5. Select an action from the menu: + + - **Delete only this provider version:** Deletes only the version of the provider you are currently viewing. + - **Delete all versions for this provider:** Deletes the entire provider and all associated versions. + +6. Type the provider name into the confirmation box and click **Delete**. + +The provider version or entire provider has been deleted from this organization's private registry and its data has been removed. Consumers will no longer be able to reference it in configurations. + +### Restoring a deleted provider + +Deletion is permanent, but you can restore a deleted private provider by re-adding it to your organization and recreating its versions and platforms. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/test.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/test.mdx new file mode 100644 index 0000000000..9b2f7084f9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/test.mdx @@ -0,0 +1,69 @@ +--- +page_title: Test private modules in the Terraform Enterprise private registry +description: Use the Terraform Enterprise private registry to run module tests. +source: terraform-docs-common +--- + +# Test private modules in the HCP Terraform private registry + +You can configure HCP Terraform to automatically run tests for modules in your private registry. When enabled, HCP Terraform will run tests for every commit to the designated branch. This lets you verify that it is safe to publish new module versions. + +## Enable testing + +If your module uses the [branch-based publishing workflow](/terraform/enterprise/registry/publish-modules#branch-based-publishing) and its source code includes [tests](/terraform/language/v1.6.x/tests), you can enable testing at any time. + +To enable testing when you publish your module: + +- Choose the **Branch** module publishing type +- Assign a branch and a module version +- Under testing, click the **Enable testing for module** checkbox +- Click **Publish module** + +To enable testing after you publishing your branch-based module: + +- Navigate to the module overview screen +- Click **Configure Tests** to open the **Tests Settings** screen +- Click **Enable testing for module** + +## Run tests remotely from the CLI + +After publishing and enabling testing for your module, you can use the Terraform CLI locally to trigger remotely-executed tests in HCP Terraform. This lets you test your module changes using the credentials configured in HCP Terraform without committing your changes to version control. + +To run your tests remotely, use the `-cloud-run` flag with the path to your module in your private registry. + +```shell +terraform test -cloud-run=app.terraform.io/:ORG/:MODULE_NAME/:PROVIDER +``` + +## Configure environment variables + +You can define test-specific environment variables that HCP Terraform will use for testing. If your tests provision infrastructure, you must configure provider credentials for the module. + +To add environment variables to your module's tests: + +1. On the module overview screen, click **Configure Tests**. +2. In the **Variables** section on the **Tests Settings** screen, click **+ Add variable**. +3. Provide a **Key** and **Value** for your environment variable, and if you want to protect the variable's value, click the **Sensitive** checkbox. `TF_VAR_x` variables of a string type that are not defined in a config must be wrapped in double-quotes. +4. Click **Add variable** to save it. + + + +## Generated module tests + +~> **Note**: Generated module tests are available in HCP Terraform **Plus** Edition and are in public beta. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. + +HCP Terraform can generate [test files](/terraform/language/tests) for any private module in your registry. You can only generate tests one time per module. + +To generate tests for your module: + +1. On the module overview screen, click **Generate tests**. +2. Click **Confirm**. It will take a few minutes to generate your module tests. +3. HCP Terraform displays generated configuration. To download all of the test files, click **Download generated tests**. +4. Create a `tests` directory in your configuration. +5. Unzip the downloaded files into the new `tests` directory. + +Generated test files remain available on the module overview page for later retrieval. Click **View test files** to view and download any previously generated tests. + +Organization owners can control this feature on the organization's [General Settings](/terraform/enterprise/users-teams-organizations/organizations#organization-settings) page. + + diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/using.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/using.mdx new file mode 100644 index 0000000000..98542f2bd7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/registry/using.mdx @@ -0,0 +1,149 @@ +--- +page_title: Use providers and modules from the Terraform Enterprise private registry +description: >- + Learn how to use providers and modules from the Terraform Enterprise private + registry in your Terraform configuration. +source: terraform-docs-common +--- + +# Use providers and modules from the HCP Terraform private registry + +All users in an organization can view the HCP Terraform private registry and use the available providers and modules. A private registry has some key requirements and differences from the [public Terraform Registry](/terraform/registry): + +- **Location:** Search for providers, modules, and usage examples in the HCP Terraform private registry UI. +- **Provider and Module block `source` argument:** Private providers and modules use a [different format](/terraform/enterprise/registry/using#using-private-providers-and-modules-in-configurations). +- **Terraform version:** HCP Terraform workspaces using version 0.11 and higher can automatically access your private modules during Terraform runs, and workspaces using version 0.13 and higher can also automatically access private providers. +- **Authentication:** If you run Terraform on the command line, you must [authenticate](/terraform/enterprise/registry/using#authentication) to HCP Terraform or your instance to use providers and modules in your organization’s private registry. + +HCP Terraform supports using modules in written configuration or through the [no-code provisioning workflow](/terraform/enterprise/no-code-provisioning/provisioning). + +## Finding Providers and Modules + +To find available providers and modules, click the **Registry** button. The **Registry** page appears. + +Click **Providers** and **Modules** to toggle back and forth between lists of available providers and modules in the private registry. You can also use the search field to filter for titles that contain a specific keyword. The search does not include READMEs or resource details. + +### Shared Providers and Modules - Terraform Enterprise + +On Terraform Enterprise, your [registry sharing](/terraform/enterprise/admin/application/registry-sharing) configuration may grant you access to another organization's providers and modules. Providers and modules that are shared with your current organization have a **Shared** badge in the private registry (below). Providers and modules in your current organization that are shared with other organizations have a badge that says **Sharing**. + +### Viewing Provider and Module Details and Versions + +Click a provider or module to view its details page. Use the **Versions** menu in the upper right to switch between the available versions, and use the **Readme**, **Inputs**, **Outputs**, **Dependencies**, and **Resources** tabs to view more information about the selected version. + +### Viewing Nested Modules and Examples + +Use the **Submodules** menu to navigate to the detail pages for any nested modules. Use the **Examples** menu to navigate to the detail pages for any available example modules. + +## Provisioning Infrastructure from No-Code Ready Modules + +You can use modules marked **No-Code Ready** to create a new workspace and automatically provision the module's resources without writing any Terraform configuration. Refer to [Provisioning No-Code Infrastructure](/terraform/enterprise/no-code-provisioning/provisioning) for details. + +## Using Public Providers and Modules in Configurations + +> **Hands-on:** Try the [Use Modules from the Registry](/terraform/tutorials/modules/module-use) tutorial. + +The syntax for public providers in a private registry is the same as for providers that you use directly from the public Terraform Registry. The syntax for the [provider block](/terraform/language/providers/configuration#provider-configuration-1) `source` argument is `/`. + +```hcl +terraform { + required_providers { + google = { + source = "hashicorp/google" + version = "4.0.0" + } + } +``` + +The syntax for referencing public modules in the [module block](/terraform/language/modules/syntax) `source` argument is `//`. + +```hcl +module "subnets" { + source = "hashicorp/subnets/cidr" + version = "1.0.0" +} +``` + +## Using Private Providers and Modules in Configurations + +The syntax for referencing private providers in the [provider block](/terraform/language/providers/configuration#provider-configuration-1) `source` argument is `//`. For the SaaS version of HCP Terraform, the hostname is `app.terraform.io`. + +```hcl +terraform { + required_providers { + random = { + source = "app.terraform.io/demo-custom-provider/random" + version = "1.1.0" + } + } +``` + +The syntax for referencing private modules in the [module block](/terraform/language/modules/syntax) `source` argument is `///`. + +- **Hostname:** For the SaaS version of HCP Terraform, use `app.terraform.io`. In Terraform Enterprise, use the hostname for your instance or the [generic hostname](/terraform/enterprise/registry/using#generic-hostname-terraform-enterprise). +- **Organization:** If you are using a shared module with Terraform Enterprise, the module's organization name may be different from your organization's name. Check the source string at the top of the module's registry page to find the proper organization name. + +```hcl +module "vpc" { + source = "app.terraform.io/example_corp/vpc/aws" + version = "1.0.4" +} +``` + +### Generic Hostname - HCP Terraform and Terraform Enterprise + +You can use the generic hostname `localterraform.com` in module sources to reference modules without modifying the HCP Terraform or Terraform Enterprise instance. When you run Terraform, it automatically requests any `localterraform.com` modules from the instance it runs on. + +```hcl +module "vpc" { + source = "localterraform.com/example_corp/vpc/aws" + version = "1.0.4" +} +``` + +~> **Important**: CLI-driven workflows require Terraform CLI v1.4.0 or above. + +To test configurations on a developer workstation without the remote backend configured, you must replace the generic hostname with a literal hostname in all module sources and then change them back before committing to VCS. We are working on making this workflow smoother, but we only recommend `localterraform.com` for large organizations that use multiple Terraform Enterprise instances. + +### Provider and Module Availability + +A workspace can only use private providers and modules from its own organization's registry. When using providers or modules from multiple organizations in the same configuration, we recommend: + +- **HCP Terraform:** [Add providers and modules to the registry](/terraform/enterprise/registry/publish-modules#sharing-modules-across-organizations) for each organization that requires access. + +- **Terraform Enterprise:** Check your site's [registry sharing](/terraform/enterprise/admin/application/registry-sharing) configuration. Workspaces can also use private providers and modules from organizations that are sharing with the workspace's organization. + +## Running Configurations with Private Providers and Modules + +### Version Requirements + +Terraform version 0.11 or later is required to use private modules in HCP Terraform workspaces and to use the CLI to apply configurations with private modules. Terraform version 0.13 and later is required to use private providers in HCP Terraform workspaces and apply configurations with private providers. + +### Authentication + +To authenticate with HCP Terraform, you can use either a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or a [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). The type of token you choose may grant different permissions. + +- **User Token**: Allows you to access providers and modules from any organization in which you are a member. You are a member of an organization if you belong to any team in that organization. You can also access modules from any organization that is sharing modules with any of your organizations. + + -> **Note:** When SAML SSO is enabled, there is a [session timeout for user API tokens](/terraform/enterprise/saml/login#api-token-expiration), requiring you to periodically re-authenticate through the web UI. Expired tokens produce a _401 Unauthorized_ error. A SAML SSO account with [IsServiceAccount](/terraform/enterprise/saml/attributes#isserviceaccount) is treated as a service account and will not have the session timeout. + +- **Team Token**: Allows you to access the private registry of that team's organization and the registries from any other organizations that have configured sharing. + +_Permissions Example_ + +A user belongs to three organizations (1, 2, and 3), and organizations 1 and 2 share access with each other. In this case, the user's token gives them access to the private registries for all of the organizations they belong to: 1, 2, and 3. However, a team token from a team in organization 1 only gives the user access to the private registry in organizations 1 and 2. + +#### Configure Authentication + +To configure authentication to HCP Terraform or your Terraform Enterprise instance, you can: + +- (Terraform 0.12.21 or later) Use the [`terraform login`](/terraform/cli/commands/login) command to obtain and save a user API token. +- Create a token and [manually configure credentials in the CLI config file][cli-credentials]. + +Make sure the hostname matches the hostname you use in provider and module sources because if the same HCP Terraform server is available at two hostnames, Terraform will not know that they reference the same server. To support multiple hostnames for provider and module sources, use the `terraform login` command multiple times and specify a different hostname each time. + +[user-token]: /terraform/enterprise/users-teams-organizations/users#api-tokens + +[cli-credentials]: /terraform/cli/config/config-file#credentials + +[permissions-citation]: #intentionally-unused---keep-for-maintainers diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2018/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2018/index.mdx new file mode 100644 index 0000000000..e95e300392 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2018/index.mdx @@ -0,0 +1,31 @@ +--- +page_title: 2018 Releases - Terraform Enterprise +description: The 2018 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2018 + +Terraform Enterprise releases from 2018 are listed in the table below. + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI** | Sentinel | +| ----------- | ---------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| v201812-2\* | 314 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.10](https://github.com/hashicorp/terraform/releases/tag/v0.11.10) | [0.6.0](https://docs.hashicorp.com/sentinel/changelog#0-6-0-november-30-2018) | +| v201812-1 | 311 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.10](https://github.com/hashicorp/terraform/releases/tag/v0.11.10) | [0.6.0](https://docs.hashicorp.com/sentinel/changelog#0-6-0-november-30-2018) | +| v201811-1 | 307 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.4.0](https://docs.hashicorp.com/sentinel/changelog#0-4-0-october-1-2018) | +| v201810-2 | 299 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.4.0](https://docs.hashicorp.com/sentinel/changelog#0-4-0-october-1-2018) | +| v201810-1 | 296 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.4.0](https://docs.hashicorp.com/sentinel/changelog#0-4-0-october-1-2018) | +| v201809-1\* | 291 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.3.1](https://docs.hashicorp.com/sentinel/changelog#0-3-1-august-3-2018) | +| v201808-2 | 288 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.3.1](https://docs.hashicorp.com/sentinel/changelog#0-3-1-august-3-2018) | +| v201808-1 | 284 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.3.1](https://docs.hashicorp.com/sentinel/changelog#0-3-1-august-3-2018) | +| v201807-2 | 281 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.3.0](https://docs.hashicorp.com/sentinel/changelog#0-3-0-july-20-2018) | +| v201807-1 | 278 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.2.0](https://docs.hashicorp.com/sentinel/changelog#0-2-0-april-11-2018) | +| v201806-2 | 275 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.2.0](https://docs.hashicorp.com/sentinel/changelog#0-2-0-april-11-2018) | +| v201806-1 | 272 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.2.0](https://docs.hashicorp.com/sentinel/changelog#0-2-0-april-11-2018) | +| v201805-1\* | 263 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.7](https://github.com/hashicorp/terraform/releases/tag/v0.11.7) | [0.2.0](https://docs.hashicorp.com/sentinel/changelog#0-2-0-april-11-2018) | +| v201804-3\* | 259 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.1](https://github.com/hashicorp/terraform/releases/tag/v0.11.1) | [0.2.0](https://docs.hashicorp.com/sentinel/changelog#0-2-0-april-11-2018) | +| v201804-2\* | 255 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.1](https://github.com/hashicorp/terraform/releases/tag/v0.11.1) | [0.1.0](https://docs.hashicorp.com/sentinel/changelog#0-1-0-september-19-2017) | +| v201804-1\* | 251 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.1](https://github.com/hashicorp/terraform/releases/tag/v0.11.1) | [0.1.0](https://docs.hashicorp.com/sentinel/changelog#0-1-0-september-19-2017) | + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2019/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2019/index.mdx new file mode 100644 index 0000000000..99c26d62f9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2019/index.mdx @@ -0,0 +1,45 @@ +--- +page_title: 2019 Releases - Terraform Enterprise +description: The 2019 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2019 + +Terraform Enterprise releases from 2019 are listed in the table below. + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI** | Sentinel | +| ----------- | ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| v201912-4 | 408 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.17](https://github.com/hashicorp/terraform/releases/tag/v0.12.17) | [0.13.0](https://docs.hashicorp.com/sentinel/changelog#0-13-0-november-15-2019) | +| v201912-3 | 407 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.17](https://github.com/hashicorp/terraform/releases/tag/v0.12.17) | [0.13.0](https://docs.hashicorp.com/sentinel/changelog#0-13-0-november-15-2019) | +| v201912-2 | 406 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.17](https://github.com/hashicorp/terraform/releases/tag/v0.12.17) | [0.13.0](https://docs.hashicorp.com/sentinel/changelog#0-13-0-november-15-2019) | +| v201912-1\* | 405 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.17](https://github.com/hashicorp/terraform/releases/tag/v0.12.17) | [0.13.0](https://docs.hashicorp.com/sentinel/changelog#0-13-0-november-15-2019) | +| v201911-3 | 403 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.12.0](https://docs.hashicorp.com/sentinel/changelog#0-12-0-october-7-2019) | +| v201911-2 | 400 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.12.0](https://docs.hashicorp.com/sentinel/changelog#0-12-0-october-7-2019) | +| v201911-1 | 397 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.12.0](https://docs.hashicorp.com/sentinel/changelog#0-12-0-october-7-2019) | +| v201910-1 | 394 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.11.0](https://docs.hashicorp.com/sentinel/changelog#0-12-0-october-7-2019) | +| v201909-3 | 390 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.4](https://docs.hashicorp.com/sentinel/changelog#0-12-0-october-7-2019) | +| v201909-2 | 387 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.4](https://docs.hashicorp.com/sentinel/changelog#0-12-0-october-7-2019) | +| v201909-1 | 384 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.4](https://docs.hashicorp.com/sentinel/changelog#0-12-0-october-7-2019) | +| v201908-2 | 381 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.2](https://docs.hashicorp.com/sentinel/changelog#0-10-2-june-25-2019) | +| v201908-1 | 378 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.2](https://docs.hashicorp.com/sentinel/changelog#0-10-2-june-25-2019) | +| v201907-1 | 374 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.2](https://docs.hashicorp.com/sentinel/changelog#0-10-2-june-25-2019) | +| v201906-2 | 370 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.1](https://docs.hashicorp.com/sentinel/changelog#0-10-1-may-9-2019) | +| v201906-1 | 367 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.2](https://github.com/hashicorp/terraform/releases/tag/v0.12.2) | [0.10.1](https://docs.hashicorp.com/sentinel/changelog#0-10-1-may-9-2019) | +| v201905-4 | 363 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.13](https://github.com/hashicorp/terraform/releases/tag/v0.11.13) | [0.10.0](https://docs.hashicorp.com/sentinel/changelog#0-10-0-april-18-2019) | +| v201905-3 | 360 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.13](https://github.com/hashicorp/terraform/releases/tag/v0.11.13) | [0.10.0](https://docs.hashicorp.com/sentinel/changelog#0-10-0-april-18-2019) | +| v201905-2 | 357 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.13](https://github.com/hashicorp/terraform/releases/tag/v0.11.13) | [0.10.0](https://docs.hashicorp.com/sentinel/changelog#0-10-0-april-18-2019) | +| v201905-1 | 354 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.13](https://github.com/hashicorp/terraform/releases/tag/v0.11.13) | [0.10.0](https://docs.hashicorp.com/sentinel/changelog#0-10-0-april-18-2019) | +| v201904-1 | 350 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.13](https://github.com/hashicorp/terraform/releases/tag/v0.11.13) | [0.9.2](https://docs.hashicorp.com/sentinel/changelog#0-9-2-march-15-2019) | +| v201903-1 | 346 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.13](https://github.com/hashicorp/terraform/releases/tag/v0.11.13) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201902-2\* | 343 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201902-1 | 340 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201901-6 | 337 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201901-5 | 334 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201901-4 | 331 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201901-3 | 327 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201901-2 | 324 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | +| v201901-1 | 319 | [2.9.2](https://release-notes.replicated.com/release-notes/2.9.2/) | [0.11.11](https://github.com/hashicorp/terraform/releases/tag/v0.11.11) | [0.8.1](https://docs.hashicorp.com/sentinel/changelog#0-8-1-january-17-2019) | + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2020/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2020/index.mdx new file mode 100644 index 0000000000..7f1e3c614b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2020/index.mdx @@ -0,0 +1,43 @@ +--- +page_title: 2020 Releases - Terraform Enterprise +description: The 2020 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2020 + +Terraform Enterprise releases from 2020 are listed in the table below. + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI** | Sentinel | +| ---------- | ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| v202012-2 | 502 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.5](https://github.com/hashicorp/terraform/releases/tag/v0.13.5) | [0.16.1](https://docs.hashicorp.com/sentinel/changelog#0-16-1-october-21-2020) | +| v202012-1 | 501 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.5](https://github.com/hashicorp/terraform/releases/tag/v0.13.5) | [0.16.1](https://docs.hashicorp.com/sentinel/changelog#0-16-1-october-21-2020) | +| v202011-2 | 487 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.5](https://github.com/hashicorp/terraform/releases/tag/v0.13.5) | [0.16.0](https://docs.hashicorp.com/sentinel/changelog#0-16-0-october-14-2020) | +| v202011-1 | 484 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.5](https://github.com/hashicorp/terraform/releases/tag/v0.13.5) | [0.16.0](https://docs.hashicorp.com/sentinel/changelog#0-16-0-october-14-2020) | +| v202010-2 | 479 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.3](https://github.com/hashicorp/terraform/releases/tag/v0.13.3) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202010-1 | 473 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.3](https://github.com/hashicorp/terraform/releases/tag/v0.13.3) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202009-2 | 462 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.0](https://github.com/hashicorp/terraform/releases/tag/v0.13.0) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202009-1 | 460 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.0](https://github.com/hashicorp/terraform/releases/tag/v0.13.0) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202008-1 | 454 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.28](https://github.com/hashicorp/terraform/releases/tag/v0.12.28) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202007-2 | 445 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.28](https://github.com/hashicorp/terraform/releases/tag/v0.12.28) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202007-1 | 444 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.28](https://github.com/hashicorp/terraform/releases/tag/v0.12.28) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202006-1 | 439 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.24](https://github.com/hashicorp/terraform/releases/tag/v0.12.24) | [0.15.5](https://docs.hashicorp.com/sentinel/changelog#0-15-5-may-20-2020) | +| v202005-2 | 430 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.24](https://github.com/hashicorp/terraform/releases/tag/v0.12.24) | [0.15.3](https://docs.hashicorp.com/sentinel/changelog#0-15-3-april-16-2020) | +| v202005-1 | 425 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.24](https://github.com/hashicorp/terraform/releases/tag/v0.12.24) | [0.15.3](https://docs.hashicorp.com/sentinel/changelog#0-15-3-april-16-2020) | +| v202004-3 | 424 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.24](https://github.com/hashicorp/terraform/releases/tag/v0.12.24) | [0.15.2](https://docs.hashicorp.com/sentinel/changelog#0-15-2-april-2-2020) | +| v202004-2 | 423 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.24](https://github.com/hashicorp/terraform/releases/tag/v0.12.24) | [0.15.2](https://docs.hashicorp.com/sentinel/changelog#0-15-2-april-2-2020) | +| v202004-1 | 422 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.24](https://github.com/hashicorp/terraform/releases/tag/v0.12.24) | [0.15.2](https://docs.hashicorp.com/sentinel/changelog#0-15-2-april-2-2020) | +| v202003-1 | 421 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.23](https://github.com/hashicorp/terraform/releases/tag/v0.12.23) | [0.15.1](https://docs.hashicorp.com/sentinel/changelog#0.15.1-october-21-2020) | +| v202002-2 | 419 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.20](https://github.com/hashicorp/terraform/releases/tag/v0.12.20) | [0.14.4](https://docs.hashicorp.com/sentinel/changelog#0-14-4-february-6-2020) | +| v202002-1b | 418 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.20](https://github.com/hashicorp/terraform/releases/tag/v0.12.20) | [0.14.4](https://docs.hashicorp.com/sentinel/changelog#0-14-4-february-6-2020) | +| v202002-1 | 417 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.20](https://github.com/hashicorp/terraform/releases/tag/v0.12.20) | [0.14.4](https://docs.hashicorp.com/sentinel/changelog#0-14-4-february-6-2020) | +| v202001-7 | 416 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.19](https://github.com/hashicorp/terraform/releases/tag/v0.12.19) | [0.14.2](https://docs.hashicorp.com/sentinel/changelog#0-14-2-january-15-2020) | +| v202001-6 | 415 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.19](https://github.com/hashicorp/terraform/releases/tag/v0.12.19) | [0.14.2](https://docs.hashicorp.com/sentinel/changelog#0-14-2-january-15-2020) | +| v202001-5 | 414 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.19](https://github.com/hashicorp/terraform/releases/tag/v0.12.19) | [0.14.2](https://docs.hashicorp.com/sentinel/changelog#0-14-2-january-15-2020) | +| v202001-4 | 413 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.19](https://github.com/hashicorp/terraform/releases/tag/v0.12.19) | [0.14.2](https://docs.hashicorp.com/sentinel/changelog#0-14-2-january-15-2020) | +| v202001-3 | 412 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.19](https://github.com/hashicorp/terraform/releases/tag/v0.12.19) | [0.14.2](https://docs.hashicorp.com/sentinel/changelog#0-14-2-january-15-2020) | +| v202001-2 | 411 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.19](https://github.com/hashicorp/terraform/releases/tag/v0.12.19) | [0.14.2](https://docs.hashicorp.com/sentinel/changelog#0-14-2-january-15-2020) | +| v202001-1 | 409 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.12.19](https://github.com/hashicorp/terraform/releases/tag/v0.12.19) | [0.14.2](https://docs.hashicorp.com/sentinel/changelog#0-14-2-january-15-2020) | + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/index.mdx new file mode 100644 index 0000000000..ef60a527fe --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/index.mdx @@ -0,0 +1,32 @@ +--- +page_title: 2021 Releases - Terraform Enterprise +description: The 2021 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2021 + +Terraform Enterprise releases from 2021 are listed in the table below. + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI** | Sentinel | +| ------------------------------------------------------------ | ---------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| [v202112-2](/terraform/enterprise/releases/2021/v202112-2) | 590 | [2.53.2](https://release-notes.replicated.com/release-notes/2.53.2/) | [1.0.11](https://github.com/hashicorp/terraform/releases/tag/v1.0.11) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | +| [v202112-1](/terraform/enterprise/releases/2021/v202112-1) | 588 | [2.53.2](https://release-notes.replicated.com/release-notes/2.53.2/) | [1.0.11](https://github.com/hashicorp/terraform/releases/tag/v1.0.11) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | +| [v202111-1](/terraform/enterprise/releases/2021/v202111-1) | 582 | [2.53.0](https://release-notes.replicated.com/release-notes/2.53.0/) | [1.0.9](https://github.com/hashicorp/terraform/releases/tag/v1.0.9) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | +| [v202110-1](/terraform/enterprise/releases/2021/v202110-1) | 576 | [2.52.0](https://release-notes.replicated.com/release-notes/2.52.0/) | [1.0.7](https://github.com/hashicorp/terraform/releases/tag/v1.0.7) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | +| [v202109-2](/terraform/enterprise/releases/2021/v202109-2) | 568 | [2.52.0](https://release-notes.replicated.com/release-notes/2.52.0/) | [1.0.5](https://github.com/hashicorp/terraform/releases/tag/v1.0.5) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | +| [v202109-1](/terraform/enterprise/releases/2021/v202109-1) | 565 | [2.52.0](https://release-notes.replicated.com/release-notes/2.52.0/) | [1.0.5](https://github.com/hashicorp/terraform/releases/tag/v1.0.5) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | +| [v202108-1](/terraform/enterprise/releases/2021/v202108-1) | 557 | [2.52.0](https://release-notes.replicated.com/release-notes/2.52.0/) | [1.0.3](https://github.com/hashicorp/terraform/releases/tag/v1.0.3) | [0.18.3](https://docs.hashicorp.com/sentinel/changelog#0-18-3-june-1-2021) | +| [v202107-1](/terraform/enterprise/releases/2021/v202107-1) | 550 | [2.50.0](https://release-notes.replicated.com/release-notes/2.50.0/) | [1.0.1](https://github.com/hashicorp/terraform/releases/tag/v1.0.1) | [0.18.3](https://docs.hashicorp.com/sentinel/changelog#0-18-3-june-1-2021) | +| [v202106-1](/terraform/enterprise/releases/2021/v202106-1) | 544 | [2.50.0](https://release-notes.replicated.com/release-notes/2.50.0/) | [1.0.0](https://github.com/hashicorp/terraform/releases/tag/v1.0.0) | [0.18.3](https://docs.hashicorp.com/sentinel/changelog#0-18-3-june-1-2021) | +| [v202105-1](/terraform/enterprise/releases/2021/v202105-1) | 534 | [2.50.0](https://release-notes.replicated.com/release-notes/2.50.0/) | [0.15.3](https://github.com/hashicorp/terraform/releases/tag/v0.15.3) | [0.18.1](https://docs.hashicorp.com/sentinel/changelog#0-18-1-may-11-2021) | +| [v202104-1](/terraform/enterprise/releases/2021/v202104-1) | 528 | [2.50.0](https://release-notes.replicated.com/release-notes/2.50.0/) | [0.15.0](https://github.com/hashicorp/terraform/releases/tag/v0.15.0) | [0.18.0](https://docs.hashicorp.com/sentinel/changelog#0-18-0-march-25-2021) | +| [v202103-3](/terraform/enterprise/releases/2021/v202103-3) | 523 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.14.7](https://github.com/hashicorp/terraform/releases/tag/v0.14.7) | [0.17.4](https://docs.hashicorp.com/sentinel/changelog#0-17-4-february-2-2021) | +| [v202103-2](/terraform/enterprise/releases/2021/v202103-2) | 520 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.14.7](https://github.com/hashicorp/terraform/releases/tag/v0.14.7) | [0.17.4](https://docs.hashicorp.com/sentinel/changelog#0-17-4-february-2-2021) | +| [v202103-1](/terraform/enterprise/releases/2021/v202103-1)\* | 519 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.14.7](https://github.com/hashicorp/terraform/releases/tag/v0.14.7) | [0.17.4](https://docs.hashicorp.com/sentinel/changelog#0-17-4-february-2-2021) | +| [v202102-2](/terraform/enterprise/releases/2021/v202102-2) | 509 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.5](https://github.com/hashicorp/terraform/releases/tag/v0.13.5) | [0.16.1](https://docs.hashicorp.com/sentinel/changelog#0-16-1-october-21-2020) | +| [v202102-1](/terraform/enterprise/releases/2021/v202102-1) | 507 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.5](https://github.com/hashicorp/terraform/releases/tag/v0.13.5) | [0.16.1](https://docs.hashicorp.com/sentinel/changelog#0-16-1-october-21-2020) | +| [v202101-1](/terraform/enterprise/releases/2021/v202101-1) | 504 | [2.29.0](https://release-notes.replicated.com/release-notes/2.29.0/) | [0.13.5](https://github.com/hashicorp/terraform/releases/tag/v0.13.5) | [0.16.1](https://docs.hashicorp.com/sentinel/changelog#0-16-1-october-21-2020) | + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202101-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202101-1.mdx new file mode 100644 index 0000000000..e27ee28a07 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202101-1.mdx @@ -0,0 +1,24 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202101-1 (504) release. +--- + +# TFE Release v202101-1 (504) + +### Upcoming Deprecation Notifications: + +* The AWS CLI that ships with Terraform Enterprise will be upgraded to AWS CLI version 2 in the next Terraform Enterprise release (v202102-1). [Version 2 of the AWS CLI contains breaking changes](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html) that could cause disruptions in custom builds. If you are currently using any AWS CLI features in your workspaces please prepare for the deprecation or migrate to a custom build image to continue using version AWS CLI version 1. + +### Application Level Breaking Changes: + +* The encryption password is no longer automatically generated and must be explicitly set by the user during installation. The encryption password can be set via the "Encryption Password" field for a manual installation and via the `enc_password` setting for an automated installation. Loss of the encryption password can lead to application data loss. To retrieve an installation's current encryption password, execute `replicatedctl app-config export --template '{{.enc_password.Value}}'`. + +### Application Level Features: + +* Enables the ability to run Terraform Enterprise in Active/Active configuration for increased reliability. If you’re interested in scaling your existing installation to two nodes, please reach out your Technical Account Manager for more information. + +### Application Level Bug Fixes: + +* Fixed issue where Forgot Password emails would not send. +* Updated the error message shown when the encryption password is empty. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202102-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202102-1.mdx new file mode 100644 index 0000000000..7964fde820 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202102-1.mdx @@ -0,0 +1,20 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202102-1 (507) release. +--- + +# TFE Release v202102-1 (507) + +### Application Level Breaking Changes: + +* The AWS CLI that ships with Terraform Enterprise will be upgraded to AWS CLI version 2. [Version 2 of the AWS CLI contains breaking changes](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html) that could cause disruptions in custom builds. If you are currently using any AWS CLI features in your workspaces please prepare for the deprecation or migrate to a custom build image to continue using version AWS CLI version 1. + +### Application Level Bug Fixes: + +* Fixed an issue where the `tfe-admin app-config` command would not accept empty configuration values. + +### Application Level Security Fixes: + +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. +* Fixed issue where password reset URLs could be seen in logs on server. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202102-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202102-2.mdx new file mode 100644 index 0000000000..c3f229c31c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202102-2.mdx @@ -0,0 +1,24 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202102-2 (509) release. +--- + +# TFE Release v202102-2 (509) + +### Bug Fixes Since v202102-1: + +* Fixed issue initializing plugins properly during Terraform Apply in certain upgrade scenarios (eg Terraform 0.12 to 0.13). + +### Application Level Breaking Changes: + +* The AWS CLI that ships with Terraform Enterprise will be upgraded to AWS CLI version 2. [Version 2 of the AWS CLI contains breaking changes](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html) that could cause disruptions in custom builds. If you are currently using any AWS CLI features in your workspaces please prepare for the deprecation or migrate to a custom build image to continue using version AWS CLI version 1. + +### Application Level Bug Fixes: + +* Fixed an issue where the `tfe-admin app-config` command would not accept empty configuration values. + +### Application Level Security Fixes: + +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. +* Fixed issue where password reset URLs could be seen in logs on server. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-1.mdx new file mode 100644 index 0000000000..54404ff7ae --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-1.mdx @@ -0,0 +1,95 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202103-1 (519) release. +--- + +# TFE Release v202103-1 (519 Required) + +### Application Level Breaking Changes: + +* The internally-managed PostgreSQL server has been upgraded from PostgreSQL 9.5 to PostgreSQL 12. Operators should back up their Terraform Enterprise data before upgrading to v202103-\* This change only affects mounted disk and proof of concept installations. Please refer to the "PostgreSQL Upgrade" section for more information. +* Changed organization name requirements to not be ambiguous with organization ID format. Although very unlikely, if an existing organization name matches a pattern `org-<16 base58 chars>`, it must be renamed. + +### Upcoming Deprecation Notifications: + +* The Admin API endpoint to list an organization's module consumers has been deprecated, and will be removed in Terraform Enterprise v202106-\* Clients should transition to the new JSON:API compliant endpoint: [List Module Consumers for an Organization](/terraform/enterprise/api-docs/admin/organizations#list-module-consumers-for-an-organization). +* The Admin API endpoint to update an organization's module consumers has been deprecated, and will be removed in Terraform Enterprise v202106-\* Clients should transition to the new JSON:API compliant endpoint: [Update an Organization's Module Consumers](/terraform/enterprise/api-docs/admin/organizations#update-an-organization-39-s-module-consumers) + +### Application Level Features: + +* Added support for PostgreSQL SCRAM-SHA-256 password authentication. +* Added `db-backup-poc`, `db-restore-poc`, and `db-reindex-poc` admin commands to allow proof of concept installations to backup, restore, and reindex the PostgreSQL database. +* Changes how TBW handles initialization during the apply phase, removing the `-backend=false` reinitialization in favor of persisting the entire filesystem between plan and apply. +* Adds Sensitive Variable Override File, which will mark TFE sensitive variables as sensitive in Terraform during runs. +* Support IMDSv2 when configuring object storage with S3 and Use Instance Profile for Access. +* Update the base OS image to Ubuntu Bionic (18.04) for the default Terraform worker image. +* Add support for forcing TLS via HSTS response headers and `Secure` cookie flags. +* Added a link to an example Terraform config repo when creating a VCS workspace. +* Added the `hostname` argument to example commands in the UI where applicable +* Added Terraform CLI versions up through 0.15.0-beta1 to Terraform Enterprise. +* Added run relationship to policy-checks API responses. +* Added ability to rename organizations in organization settings. +* Added the ability to filter JSON results in select places where JSON data is available (such as the state viewer). The filter language is a jq subset; see the documentation for more details. +* Added the ability to see the JSON response for policy checks within the run viewer, along with a shortcut to quickly see the results for all "main" rules within a policy check. +* Added the workspace name to the page title +* Fixed streamed log undefined waiting text +* Fixed log viewer printing "undefined" for empty logs +* Added Additional VCS Info to Workspace API Response +* Added ability to view module submodules in the private registry +* Added ability to view module examples in the private registry. +* Added JSON:API compliant endpoint to fetch an organization's module consumers. +* Added JSON:API compliant endpoint to update an organization's module consumers. +* Added ability to filter module producing organizations to the admin/organizations API endpoint. +* Added the ability to include the related run and workspace to the policy checks API endpoint. +* Changed team access API to only use pagination when requested. + +### Application Level Bug Fixes: + +* Upgrades go-isolation to pick up bug fix for directories with spaces in the name. +* Adjust container permissions to support running `tfe-admin` commands in environments where SELinux operates in `enforcing` mode. +* Fix a race condition in Active/Active deployments that would potentially result in transient Vault authentication failures when using an internal Vault deployment. +* Fixed an issue where the footer did not display for logged-in users. +* Fixed a bug where a workspace would think it had a working configuration version after someone ran `terraform plan`, but it wouldn't be able to queue new runs. +* Fixed keyboard accessibility for modules in the private registry +* Changed admin organizations api returns 422 if global_module_sharing: null passed in +* Fixed an issue with the reliability of copying text from log output in the Google Chrome browser +* Fixed an inconsistency of icon colors within certain button types. +* Fixed alignment and icon issues on Notifications page +* Added ability to keyboard-navigate into streamed logs on a run and provisioning instructions on a module +* Fixed pagination params for page size and number for audit trail endpoint +* Fixed sourceable run trigger dropdown when there are more than 50 workspaces available +* Changed instructions to add a new GitHub.com (custom) provider to align with a change to the GitHub UI/UX +* Fixed email logos not rendering if `ASSET_HOST` is not set in a TFE instance +* Fixed GitHub icon rendering in Firefox +* Added keyboard-only navigation to workspace heading links +* Added keyboard-only navigation for accordion elements such as run phase expanding boxes. +* Fixed accessibility of heading order for screen readers +* Fixed price error for certain AWS Elasticache node types during Cost Estimation. +* Fixed a potential issue where some cost estimates might be off by 1-2% +* Fixed the user invitation modal list of teams, ensuring teams are correctly paginated to include all of them. +* Fixed an issue where working directories were having their leading and trailing slashes stripped during updating. +* Fixed Modules ingress for Bitbucket Webhook events containing multiple changes. +* Fixed an issue where custom CA certificates were not being passed to the `telegraf` container. +* Fixed API issue where includable resource parameters were required to be underscored, even as the API is generally hyphenated. +* Fixed workspace variables API to require the correct workspace in URL +* Fixed issue not showing all teams when adding team access to a workspace. + +### Application Level Security Fixes: + +* Enforce organization-level setting that requires users within an organization to have two-factor authentication enabled (CVE-2021-3153). +* Reduce exposure by proactively revoking per-run tokens on run completion. +* Update go-slug to v0.5.0 to pick up security fixes for maliciously crafted tarballs. +* Update Rails to 6.0.3.5, addressing security vulnerabilities. +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. + +### PostgreSQL Upgrade: + +The [PostgreSQL versioning policy](https://www.postgresql.org/support/versioning/) states that PostgreSQL 9.5 had its final release on February 11, 202\* As such, the internally-managed PostgreSQL server has been upgraded from PostgreSQL 9.5 to PostgreSQL 12. This change only affects mounted disk and proof of concept installations. It does not affect external services installations. + +The first time a Terraform Enterprise installation is upgraded to v202103-1, a program will be executed that will upgrade the PostgreSQL 9.5 data to PostgreSQL 12. This program takes a backup of the PostgreSQL data before upgrading. Regardless, operators should back up their Terraform Enterprise data before upgrading to Terraform Enterprise v202103-\* + +Additionally, operators should familiarize themselves with the following knowledge base articles. + +* [How to Manually Backup Internally-Managed PostgreSQL Data](https://support.hashicorp.com/hc/en-us/articles/1500003527861) +* [PostgreSQL 12 Upgrade Error: Timeout waiting for event PostgreSQL Upgraded](https://support.hashicorp.com/hc/en-us/articles/1500003501501) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-2.mdx new file mode 100644 index 0000000000..b6de103581 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-2.mdx @@ -0,0 +1,99 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202103-2 (520) release. +--- + +# TFE Release v202103-2 (520) + +### Bug Fixes Since v202103-1: + +* Fixed an issue where runs would fail to plan when using Terraform 0.13.x versions created with `terraform-bundle`. + +### Application Level Breaking Changes: + +* The internally-managed PostgreSQL server has been upgraded from PostgreSQL 9.5 to PostgreSQL 12. Operators should back up their Terraform Enterprise data before upgrading to v202103-1. This change only affects mounted disk and proof of concept installations. Please refer to the "PostgreSQL Upgrade" section for more information. +* Changed organization name requirements to not be ambiguous with organization ID format. Although very unlikely, if an existing organization name matches a pattern `org-<16 base58 chars>`, it must be renamed. + +### Upcoming Deprecation Notifications: + +* The Admin API endpoint to list an organization's module consumers has been deprecated, and will be removed in Terraform Enterprise v202106-1. Clients should transition to the new JSON:API compliant endpoint: [List Module Consumers for an Organization](/terraform/enterprise/api-docs/admin/organizations#list-module-consumers-for-an-organization). +* The Admin API endpoint to update an organization's module consumers has been deprecated, and will be removed in Terraform Enterprise v202106-1. Clients should transition to the new JSON:API compliant endpoint: [Update an Organization's Module Consumers](/terraform/enterprise/api-docs/admin/organizations#update-an-organization-39-s-module-consumers) + +### Application Level Features: + +* Added support for PostgreSQL SCRAM-SHA-256 password authentication. +* Added `db-backup-poc`, `db-restore-poc`, and `db-reindex-poc` admin commands to allow proof of concept installations to backup, restore, and reindex the PostgreSQL database. +* Changes how TBW handles initialization during the apply phase, removing the `-backend=false` reinitialization in favor of persisting the entire filesystem between plan and apply. +* Adds Sensitive Variable Override File, which will mark TFE sensitive variables as sensitive in Terraform during runs. +* Support IMDSv2 when configuring object storage with S3 and Use Instance Profile for Access. +* Update the base OS image to Ubuntu Bionic (18.04) for the default Terraform worker image. +* Add support for forcing TLS via HSTS response headers and `Secure` cookie flags. +* Added a link to an example Terraform config repo when creating a VCS workspace. +* Added the `hostname` argument to example commands in the UI where applicable +* Added Terraform CLI versions up through 0.15.0-beta1 to Terraform Enterprise. +* Added run relationship to policy-checks API responses. +* Added ability to rename organizations in organization settings. +* Added the ability to filter JSON results in select places where JSON data is available (such as the state viewer). The filter language is a jq subset; see the documentation for more details. +* Added the ability to see the JSON response for policy checks within the run viewer, along with a shortcut to quickly see the results for all "main" rules within a policy check. +* Added the workspace name to the page title +* Fixed streamed log undefined waiting text +* Fixed log viewer printing "undefined" for empty logs +* Added Additional VCS Info to Workspace API Response +* Added ability to view module submodules in the private registry +* Added ability to view module examples in the private registry. +* Added JSON:API compliant endpoint to fetch an organization's module consumers. +* Added JSON:API compliant endpoint to update an organization's module consumers. +* Added ability to filter module producing organizations to the admin/organizations API endpoint. +* Added the ability to include the related run and workspace to the policy checks API endpoint. +* Changed team access API to only use pagination when requested. + +### Application Level Bug Fixes: + +* Upgrades go-isolation to pick up bug fix for directories with spaces in the name. +* Adjust container permissions to support running `tfe-admin` commands in environments where SELinux operates in `enforcing` mode. +* Fix a race condition in Active/Active deployments that would potentially result in transient Vault authentication failures when using an internal Vault deployment. +* Fixed an issue where the footer did not display for logged-in users. +* Fixed a bug where a workspace would think it had a working configuration version after someone ran `terraform plan`, but it wouldn't be able to queue new runs. +* Fixed keyboard accessibility for modules in the private registry +* Changed admin organizations api returns 422 if global_module_sharing: null passed in +* Fixed an issue with the reliability of copying text from log output in the Google Chrome browser +* Fixed an inconsistency of icon colors within certain button types. +* Fixed alignment and icon issues on Notifications page +* Added ability to keyboard-navigate into streamed logs on a run and provisioning instructions on a module +* Fixed pagination params for page size and number for audit trail endpoint +* Fixed sourceable run trigger dropdown when there are more than 50 workspaces available +* Changed instructions to add a new GitHub.com (custom) provider to align with a change to the GitHub UI/UX +* Fixed email logos not rendering if `ASSET_HOST` is not set in a TFE instance +* Fixed GitHub icon rendering in Firefox +* Added keyboard-only navigation to workspace heading links +* Added keyboard-only navigation for accordion elements such as run phase expanding boxes. +* Fixed accessibility of heading order for screen readers +* Fixed price error for certain AWS Elasticache node types during Cost Estimation. +* Fixed a potential issue where some cost estimates might be off by 1-2% +* Fixed the user invitation modal list of teams, ensuring teams are correctly paginated to include all of them. +* Fixed an issue where working directories were having their leading and trailing slashes stripped during updating. +* Fixed Modules ingress for Bitbucket Webhook events containing multiple changes. +* Fixed an issue where custom CA certificates were not being passed to the `telegraf` container. +* Fixed API issue where includable resource parameters were required to be underscored, even as the API is generally hyphenated. +* Fixed workspace variables API to require the correct workspace in URL +* Fixed issue not showing all teams when adding team access to a workspace. + +### Application Level Security Fixes: + +* Enforce organization-level setting that requires users within an organization to have two-factor authentication enabled (CVE-2021-3153). +* Reduce exposure by proactively revoking per-run tokens on run completion. +* Update go-slug to v0.5.0 to pick up security fixes for maliciously crafted tarballs. +* Update Rails to 6.0.3.5, addressing security vulnerabilities. +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. + +### PostgreSQL Upgrade: + +The [PostgreSQL versioning policy](https://www.postgresql.org/support/versioning/) states that PostgreSQL 9.5 had its final release on February 11, 2021. As such, the internally-managed PostgreSQL server has been upgraded from PostgreSQL 9.5 to PostgreSQL 12. This change only affects mounted disk and proof of concept installations. It does not affect external services installations. + +The first time a Terraform Enterprise installation is upgraded to v202103-1, a program will be executed that will upgrade the PostgreSQL 9.5 data to PostgreSQL 12. This program takes a backup of the PostgreSQL data before upgrading. Regardless, operators should back up their Terraform Enterprise data before upgrading to Terraform Enterprise v202103-1. + +Additionally, operators should familiarize themselves with the following knowledge base articles. + +* [How to Manually Backup Internally-Managed PostgreSQL Data](https://support.hashicorp.com/hc/en-us/articles/1500003527861) +* [PostgreSQL 12 Upgrade Error: Timeout waiting for event PostgreSQL Upgraded](https://support.hashicorp.com/hc/en-us/articles/1500003501501) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-3.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-3.mdx new file mode 100644 index 0000000000..9ff13d4679 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202103-3.mdx @@ -0,0 +1,103 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202103-3 (523) release. +--- + +# TFE Release v202103-3 (523) + +### Bug Fixes Since v202103-2: + +* Fixed an issue where certain ephemeral Docker volumes were inadvertently included in Replicated snapshots, leading to snapshot timeouts. + +### Bug Fixes Since v202103-1: + +* Fixed an issue where runs would fail to plan when using Terraform 0.13.x versions created with `terraform-bundle`. + +### Application Level Breaking Changes: + +* The internally-managed PostgreSQL server has been upgraded from PostgreSQL 9.5 to PostgreSQL 12. Operators should back up their Terraform Enterprise data before upgrading to v202103-1. This change only affects mounted disk and proof of concept installations. Please refer to the "PostgreSQL Upgrade" section for more information. +* Changed organization name requirements to not be ambiguous with organization ID format. Although very unlikely, if an existing organization name matches a pattern `org-<16 base58 chars>`, it must be renamed. + +### Upcoming Deprecation Notifications: + +* The Admin API endpoint to list an organization's module consumers has been deprecated, and will be removed in Terraform Enterprise v202106-1. Clients should transition to the new JSON:API compliant endpoint: [List Module Consumers for an Organization](/terraform/enterprise/api-docs/admin/organizations#list-module-consumers-for-an-organization). +* The Admin API endpoint to update an organization's module consumers has been deprecated, and will be removed in Terraform Enterprise v202106-1. Clients should transition to the new JSON:API compliant endpoint: [Update an Organization's Module Consumers](/terraform/enterprise/api-docs/admin/organizations#update-an-organization-39-s-module-consumers) + +### Application Level Features: + +* Added support for PostgreSQL SCRAM-SHA-256 password authentication. +* Added `db-backup-poc`, `db-restore-poc`, and `db-reindex-poc` admin commands to allow proof of concept installations to backup, restore, and reindex the PostgreSQL database. +* Changes how TBW handles initialization during the apply phase, removing the `-backend=false` reinitialization in favor of persisting the entire filesystem between plan and apply. +* Adds Sensitive Variable Override File, which will mark TFE sensitive variables as sensitive in Terraform during runs. +* Support IMDSv2 when configuring object storage with S3 and Use Instance Profile for Access. +* Update the base OS image to Ubuntu Bionic (18.04) for the default Terraform worker image. +* Add support for forcing TLS via HSTS response headers and `Secure` cookie flags. +* Added a link to an example Terraform config repo when creating a VCS workspace. +* Added the `hostname` argument to example commands in the UI where applicable +* Added Terraform CLI versions up through 0.15.0-beta1 to Terraform Enterprise. +* Added run relationship to policy-checks API responses. +* Added ability to rename organizations in organization settings. +* Added the ability to filter JSON results in select places where JSON data is available (such as the state viewer). The filter language is a jq subset; see the documentation for more details. +* Added the ability to see the JSON response for policy checks within the run viewer, along with a shortcut to quickly see the results for all "main" rules within a policy check. +* Added the workspace name to the page title +* Fixed streamed log undefined waiting text +* Fixed log viewer printing "undefined" for empty logs +* Added Additional VCS Info to Workspace API Response +* Added ability to view module submodules in the private registry +* Added ability to view module examples in the private registry. +* Added JSON:API compliant endpoint to fetch an organization's module consumers. +* Added JSON:API compliant endpoint to update an organization's module consumers. +* Added ability to filter module producing organizations to the admin/organizations API endpoint. +* Added the ability to include the related run and workspace to the policy checks API endpoint. +* Changed team access API to only use pagination when requested. + +### Application Level Bug Fixes: + +* Upgrades go-isolation to pick up bug fix for directories with spaces in the name. +* Adjust container permissions to support running `tfe-admin` commands in environments where SELinux operates in `enforcing` mode. +* Fix a race condition in Active/Active deployments that would potentially result in transient Vault authentication failures when using an internal Vault deployment. +* Fixed an issue where the footer did not display for logged-in users. +* Fixed a bug where a workspace would think it had a working configuration version after someone ran `terraform plan`, but it wouldn't be able to queue new runs. +* Fixed keyboard accessibility for modules in the private registry +* Changed admin organizations api returns 422 if global_module_sharing: null passed in +* Fixed an issue with the reliability of copying text from log output in the Google Chrome browser +* Fixed an inconsistency of icon colors within certain button types. +* Fixed alignment and icon issues on Notifications page +* Added ability to keyboard-navigate into streamed logs on a run and provisioning instructions on a module +* Fixed pagination params for page size and number for audit trail endpoint +* Fixed sourceable run trigger dropdown when there are more than 50 workspaces available +* Changed instructions to add a new GitHub.com (custom) provider to align with a change to the GitHub UI/UX +* Fixed email logos not rendering if `ASSET_HOST` is not set in a TFE instance +* Fixed GitHub icon rendering in Firefox +* Added keyboard-only navigation to workspace heading links +* Added keyboard-only navigation for accordion elements such as run phase expanding boxes. +* Fixed accessibility of heading order for screen readers +* Fixed price error for certain AWS Elasticache node types during Cost Estimation. +* Fixed a potential issue where some cost estimates might be off by 1-2% +* Fixed the user invitation modal list of teams, ensuring teams are correctly paginated to include all of them. +* Fixed an issue where working directories were having their leading and trailing slashes stripped during updating. +* Fixed Modules ingress for Bitbucket Webhook events containing multiple changes. +* Fixed an issue where custom CA certificates were not being passed to the `telegraf` container. +* Fixed API issue where includable resource parameters were required to be underscored, even as the API is generally hyphenated. +* Fixed workspace variables API to require the correct workspace in URL +* Fixed issue not showing all teams when adding team access to a workspace. + +### Application Level Security Fixes: + +* Enforce organization-level setting that requires users within an organization to have two-factor authentication enabled (CVE-2021-3153). +* Reduce exposure by proactively revoking per-run tokens on run completion. +* Update go-slug to v0.5.0 to pick up security fixes for maliciously crafted tarballs. +* Update Rails to 6.0.3.5, addressing security vulnerabilities. +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. + +### PostgreSQL Upgrade: + +The [PostgreSQL versioning policy](https://www.postgresql.org/support/versioning/) states that PostgreSQL 9.5 had its final release on February 11, 2021. As such, the internally-managed PostgreSQL server has been upgraded from PostgreSQL 9.5 to PostgreSQL 12. This change only affects mounted disk and proof of concept installations. It does not affect external services installations. + +The first time a Terraform Enterprise installation is upgraded to v202103-1, a program will be executed that will upgrade the PostgreSQL 9.5 data to PostgreSQL 12. This program takes a backup of the PostgreSQL data before upgrading. Regardless, operators should back up their Terraform Enterprise data before upgrading to Terraform Enterprise v202103-1. + +Additionally, operators should familiarize themselves with the following knowledge base articles. + +* [How to Manually Backup Internally-Managed PostgreSQL Data](https://support.hashicorp.com/hc/en-us/articles/1500003527861) +* [PostgreSQL 12 Upgrade Error: Timeout waiting for event PostgreSQL Upgraded](https://support.hashicorp.com/hc/en-us/articles/1500003501501) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202104-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202104-1.mdx new file mode 100644 index 0000000000..ed4a7cf882 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202104-1.mdx @@ -0,0 +1,42 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202104-1 (528) release. +--- + +# TFE Release v202104-1 (528) + +### Application Level Breaking Changes: + +- Added a new organization permission, "Manage Policy Overrides", to isolate the permission for allowing overrides of `soft-mandatory` policy checks. The existing "Manage Policies" permission will no longer allow for `soft-mandatory` overrides. +- Increased minimim required Replicated version to 2.50.0. + +### Application Level Features: + +- Added policy check events to the audit log and audit trail APIs. +- Added ability to define working directory while changing a workspace's VCS source +- Changed the Sentinel runtime to version 0.18.0. For the latest changes, see the [release notes](https://docs.hashicorp.com/sentinel/changelog). +- Changed Modules page to be Registry and updated urls +- Added Terraform CLI versions up through 0.15.0 to Terraform Enterprise. +- Added the ability to restrict state access (usually performed via the `terraform_remote_state` data source) to specific workspaces within an organization, along with an admin setting to configure the default setting for new workspaces and a command line migration assistant. +- Added UI for disabling automatic speculative plans in VCS-connected workspaces. (This already existed in the API, and is now also available in each workspace's VCS settings page.) +- Added Firefox ESR and older Chrome/Firefox/Safari/Edge versions (latest 2) to browser support list +- Added Replicated configuration to restrict Terraform run environments from being able to reach cloud provider metadata endpoints, e.g., `http://169.254.169.254`. +- Active/Active configurations now require fewer tokens during install, only needing `enc_password` across all nodes (previously required tokens such as `cookie_hash`, `install_id` etc) See [documentation for more details](/terraform/enterprise/v202104-1/replicated/install/automated/active-active). + +### Application Level Bug Fixes: + +- Fixed an issue where `tfe-admin support-bundle` would fail to upload support bundles to S3 due to permissions issues. +- Fixed an issue where the Backup and Restore API would restore files to the root of the Azure storage account instead of inside the configured Azure blob container. +- Changed GitHub token validation to accept new formats +- Changed maximum displayable teams to 500 from 250 on team access selection wizard +- Fixed an issue in JSON filtering where unknown keys were not being handled as expected by jq (missing keys should render null values). + +### Application Level Security Fixes: + +- Removed the logic to upgrade the internally-managed PostgreSQL server from PostgreSQL 9.5 to PostgreSQL 12. Installations running a release of Terraform Enterprise prior to v202103-1 must upgrade to required release v202103-1 in order to upgrade the internally-managed PostgreSQL server. This change only affects mounted disk and proof of concept installations. +- Rotated the secret used to generate password reset tokens and account unlock tokens. Existing password reset tokens and account unlock tokens generated before this change is deployed will be rendered invalid. +- Removed the ability for run tokens used in build workers to list all workspaces in the organization, a permission that is not required for the run token's intended purpose of reading workspaces to share state across workspaces using the terraform_remote_state data source. +- Removed the ability for Terraform code in a run environment to initiate network communication with internal TFE services. +- Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. +- Introduced additional security controls to prevent SSRF attacks in various TFE components. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202105-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202105-1.mdx new file mode 100644 index 0000000000..74dc6aaa99 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202105-1.mdx @@ -0,0 +1,42 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202105-1 (534) release. +--- + +# TFE Release v202105-1 (534) + +### Application Level Features: + +* Changed run page to keep apply logs open after an active run completes. +* Added "Created via" to the sidebar +* Added Link as the Run Triggers header +* Changed count display for run triggers +* Changed submodule and examples UI +* Added Terraform CLI versions up through 0.15.3 to Terraform Enterprise. +* Changed the maximum Sentinel job execution time to 1 hour. +* Changed the Sentinel runtime to version 0.18.1. For the latest changes, see the [release notes](https://docs.hashicorp.com/sentinel/changelog). +* Changed mock generation so that: 1) best efforts are made to obfuscate sensitive values, and 2) generate the sample configuration file as HCL instead of legacy JSON. + +### Application Level Bug Fixes: + +* Fixed plan logs upload expiration to match the actual maximum plan runtime. +* Reduce Terraform State Parser maximum memory usage on small states. +* Fixed error when deleting workspaces +* Fixed OOM errors when deleting large workspaces +* Fixed run trigger scrollbars when overflow is present +* Fixed module view published date bug. +* Fixed an issue where a user couldn't accept an invitation if they'd ever had an expired invite. +* Fixed an issue preventing users who had an invalid invitation token from clicking through to the sign up form. +* Fixed some communication components between the Sentinel worker and TFE internal API to ensure the worker does not execute a policy check before it is ready. +* Fixed an issue where policy check results were being submitted for already completed checks, causing confusing results (passing results for failed checks, for example). +* Changed refresh interval for GitLab.com OAuth Token refreshes. +* Fixed unpacking custom provider binaries when using Terraform 0.14.x and 0.15.x. +* Changed frontend route params for organization and workspace names case insensitive +* Changed retry behavior to not retry HTTP basic auth failures when ingressing configurations + +### Application Level Security Fixes: + +* Added `autocomplete=off` attribute to password fields +* Updated the Ruby version used by the application to 2.7.3. +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202106-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202106-1.mdx new file mode 100644 index 0000000000..27df2522bf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202106-1.mdx @@ -0,0 +1,41 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202106-1 (544) release. +--- + +# TFE Release v202106-1 (544) + +### Application Level Features: + +- Added support for several new capabilities in remote runs triggered via the CLI and API: `-refresh=false`, `-refresh-only`, and `-replace=ADDRESS`. See [the documentation](/terraform/cloud-docs/run/modes-and-options) for more details on each of these options. +- Added Terraform CLI versions up through 0.15.5 to Terraform Enterprise. +- Changed Terraform Cost Estimation to use the new, free Azure pricing API. This changes the [Azure egress hostname](/terraform/enterprise/v202106-1/replicated/requirements/network#prices-azure-com) to `prices.azure.com`. +- Updated the UX for the Registry +- Changed the Sentinel runtime to version 0.18.3. For the latest changes, see the [release notes](https://docs.hashicorp.com/sentinel/changelog). + +### Application Level Bug Fixes: + +- Upgrade Golang 1.14.0 => 1.16.4 +- Fixed unexpected exceptions when accessing a JSON plan that was created before April 2019. +- Fix issue where runs might get stuck in cost estimating +- Fixed an authorisation check for service accounts and SSO, which prevented service account created runs from being auto applied. +- Fixed an issue that prevented commenting on runs by certain users who otherwise should be permissed. +- Fixed support for Azure appservice v2/V2 tiers with spaces +- Fixed an issue where Sentinel VCS status checks were not receiving a response from speculative plans. +- Fixed a potential conflict condition when starting multiple TFE instances simultaneously. + +### Application Level Security Fixes: + +- The Vault unseal key and root token are no longer persisted to disk in the Vault container. +- The PostgreSQL 9.5 to 12 upgrade container has been removed. +- The PostgreSQL default password migration container has been removed. + +### API: + +- Updated [Registry Module APIs](/terraform/cloud-docs/api-docs/private-registry/modules). + - added `registry_name` scoped APIs. + - added `organization_name` scoped APIs. + - added [Module List API](/terraform/cloud-docs/api-docs/private-registry/modules#list-registry-modules-for-an-organization). + - updated [Module Delete APIs](/terraform/cloud-docs/api-docs/private-registry/modules#delete-a-module). +- [Runs](/terraform/cloud-docs/api-docs/run): added `refresh`, `refresh-only`, and `replace-addrs` attributes. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202107-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202107-1.mdx new file mode 100644 index 0000000000..50fbf25ff3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202107-1.mdx @@ -0,0 +1,34 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202107-1 (550) release. +--- + +# TFE Release v202107-1 (550) + +### Application Level Breaking Changes: + +* Changed default run messages to no longer include detailed information about the run (destroy run, resource targets, etc.). Instead, destroy runs and refresh-only runs are now clearly labeled wherever they're displayed. + +### Application Level Features: + +* Added labels for destroy runs and refresh-only runs in workspace run lists. +* Modified preflight checks to use HTTP and the system HTTP proxy when verifying connectivity to releases.hashicorp.com. +* Added structured run output for the apply phase of a run. New Apply User Interface +* Changed the organization settings left navigation sidebar into thematic groups, with settings in alphabetical order within a group. + +### Application Level Bug Fixes: + +* Fixed icon rendering on workspace overviews in safari +* Fixed typo in policy sets UI +* Fixed slow module search API endpoint which could cause performance issues for terraform-registry. +* Fixed creating apply-able Runs for Bitbucket Server +* Fixed error running Cost Estimation on Terraform 1.0.1 plans +* Fixed extra border on run phases expandable boxes +* Fixed modal dialog focus trap issues +* Fixed module change version drop down with only one version + +### Application Level Security Fixes: + +* Addressed authorization flaw that allowed privilege escalation via the TFE run token (HCSEC-2021-18 / CVE-2021-36230). +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202108-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202108-1.mdx new file mode 100644 index 0000000000..94eaa94821 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202108-1.mdx @@ -0,0 +1,45 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202108-1 (557) release. +--- + +# TFE Release v202108-1 (557) + +### Application Level Features: + +* Added run metadata to Docker containers performing Terraform operations +* Added Terraform CLI versions up through 1.0.3 to Terraform Enterprise. +* Added `locked_by` as an includable resource in the workspaces API. +* Added ability for organization tokens to manage workspace notification configurations. +* Updated run status badges and filtering options +* Added the [Workspace Overview to Terraform Cloud](https://www.hashicorp.com/blog/new-workspace-overview-for-terraform-cloud) capability for Enterprise environments, including the newly released resource grid. +* Added the ability to group and filter workspaces using singleton tags. + +### Application Level Bug Fixes: + +* Fixed broken GitLab.com OAuth Application registration link. +* Fixed handling Oauth Token refresh on failed workspace updates. +* Fixed incorrect display of apply logs for canceled runs. +* Fixed bug where JSON plan output was only kept for a week after run completion. +* Fixed broken API token copy buttons in some browsers. +* Fixed workspace relationship ID in state version API +* Fixed organization settings navigation by hiding sections and switching to sentence case + +### Application Level Security Fixes: + +* Removed the ability for new users to change two-factor authentication settings without first confirming their email. +* Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. + +### API: + +* Introduced Workspace Tagging + * Updated [Workspaces](/terraform/cloud-docs/api-docs/workspaces): + * added `tag_names` attribute. + * added `POST /workspaces/:workspace_id/relationships/tags` + * added `DELETE /workspaces/workspace-2/relationships/tags` + * Added [Organization Tags](/terraform/cloud-docs/api-docs/organization-tags). + * Added `tags` attribute to [`tfrun`](/terraform/cloud-docs/policy-enforcement/sentinel/import/tfrun) +* [Notification configurations](/terraform/cloud-docs/api-docs/notification-configurations): Gave organization tokens permission to create and manage notification configurations. +* [State versions](/terraform/cloud-docs/api-docs/state-versions): Fixed the ID format for the workspace relationship of a state version. Previously, the reported ID was unusable due to a bug. +* [Workspaces](/terraform/cloud-docs/api-docs/workspaces): Added `locked_by` as an includable related resource. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202109-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202109-1.mdx new file mode 100644 index 0000000000..f8498ff9ff --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202109-1.mdx @@ -0,0 +1,53 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202109-1 (565) release. +--- + +# TFE Release v202109-1 (565) + +## Known Issues + +1. [February 8, 2022] This release includes a regression that removed default log rotation settings of Docker logs using the `json-file` logging driver (the default driver), affecting log rotation on installations with the new log forwarding feature disabled. If you do not enable the log forwarding feature on your installation, we recommend that you configure global log rotation settings to prevent disk space issues. For more information about configuring log rotation, refer to [Log Rotation](/terraform/enterprise/v202109-1/replicated/install/pre-install-checklist#log-rotation). This issue is fixed in v202201-2. + +## Deprecation Notice + +The following operating systems are no longer supported: + +- Ubuntu 14 +- Debian 7 + +Docker logs using the `json-file` logging driver (the default driver) will no longer be automatically rotated. Please refer to the [log rotation documentation](/terraform/enterprise/v202109-1/replicated/install/pre-install-checklist#log-rotation) for details on how to configure log rotation. + +## Application Level Features + +1. Added Terraform CLI versions up through 1.1.0-alpha20210811 to Terraform Enterprise. +1. Added 'capacity_cpus' Replicated configuration option to limit the number of CPU cores available to individual Terraform runs. +1. Changed structured run UI to always show error logs immediately. +1. Changed apply UI to show "no changes" for runs which only change outputs. +1. Changed apply UI to hide output values by default, and improved display of complex values. +1. Added advanced UI for Terraform Plan, including an interactive diff. +1. Added support for Terraform Cloud Agents. +1. Added support for forwarding Terraform Enterprise logs to one or more external destinations. + +## Application Level Bug Fixes + +1. Fixed sidekiq admin panel to be accessible to Configuration and Support admin RBAC roles. +1. Changed apply progress UI for to clarify the final state of replaced resources. +1. Updated Nomad to 1.1.4 +1. Updated Vault to 1.8.2 +1. Fixed registry modules with errors so that they are accessible. +1. Updated Sentinel to 0.18.4 +1. Updated Telegraf to 1.19.3 to fix a `panic: runtime error: slice bounds out of range` error. +1. Updated InfluxDB to 1.8.9. + +## Application Level Security Fixes + +1. Hid the upload-url attribute on ConfigurationVersion API resources after the initial create action in order to prevent a privilege escalation. +1. Mitigated a potential Host header injection vulnerability. +1. Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. + +## API + +1. Introduced the [State Version Outputs](/terraform/cloud-docs/api-docs/state-versions) endpoint to retrieve the Outputs for a given State Version +1. **Breaking** Security fix to [Configuration versions](/terraform/cloud-docs/api-docs/configuration-versions): upload-url attribute for [uploading configuration files](/terraform/cloud-docs/api-docs/configuration-versions#upload-configuration-files) is now only available on the create response. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202109-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202109-2.mdx new file mode 100644 index 0000000000..c85f383a16 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202109-2.mdx @@ -0,0 +1,57 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202109-2 (568) release. +--- + +# TFE Release v202109-2 (568) + +## Known Issues + +1. [February 8, 2022] This release includes a regression that removed default log rotation settings of Docker logs using the `json-file` logging driver (the default driver), affecting log rotation on installations with the new log forwarding feature disabled. If you do not enable the log forwarding feature, we recommend that you configure global log rotation settings to prevent disk space issues. For more information about configuring log rotation, refer to [Log Rotation](/terraform/enterprise/v202109-2/replicated/install/pre-install-checklist#log-rotation). This issue is fixed in v202201-2. + +## Application Level Bug Fixes Since v202109-1 + +1. Updated Fluent Bit to v1.8.7 to fix a DNS resolution issue which prevents operators from sending logs to Datadog. + +## Deprecation Notice + +The following operating systems are no longer supported: + +- Ubuntu 14 +- Debian 7 + +Docker logs using the `json-file` logging driver (the default driver) will no longer be automatically rotated. Please refer to the [log rotation documentation](/terraform/enterprise/v202109-2/replicated/install/pre-install-checklist#log-rotation) for details on how to configure log rotation. + +## Application Level Features + +1. Added Terraform CLI versions up through 1.1.0-alpha20210811 to Terraform Enterprise. +1. Added 'capacity_cpus' Replicated configuration option to limit the number of CPU cores available to individual Terraform runs. +1. Changed structured run UI to always show error logs immediately. +1. Changed apply UI to show "no changes" for runs which only change outputs. +1. Changed apply UI to hide output values by default, and improved display of complex values. +1. Added advanced UI for Terraform Plan, including an interactive diff. +1. Added support for Terraform Cloud Agents. +1. Added support for forwarding Terraform Enterprise logs to one or more external destinations. + +## Application Level Bug Fixes + +1. Fixed sidekiq admin panel to be accessible to Configuration and Support admin RBAC roles. +1. Changed apply progress UI for to clarify the final state of replaced resources. +1. Updated Nomad to 1.1.4 +1. Updated Vault to 1.8.2 +1. Fixed registry modules with errors so that they are accessible. +1. Updated Sentinel to 0.18.4 +1. Updated Telegraf to 1.19.3 to fix a `panic: runtime error: slice bounds out of range` error. +1. Updated InfluxDB to 1.8.9. + +## Application Level Security Fixes + +1. Hid the upload-url attribute on ConfigurationVersion API resources after the initial create action in order to prevent a privilege escalation. +1. Mitigated a potential Host header injection vulnerability. +1. Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. + +## API + +1. Introduced the [State Version Outputs](/terraform/cloud-docs/api-docs/state-versions) endpoint to retrieve the Outputs for a given State Version +1. **Breaking** Security fix to [Configuration versions](/terraform/cloud-docs/api-docs/configuration-versions): upload-url attribute for [uploading configuration files](/terraform/cloud-docs/api-docs/configuration-versions#upload-configuration-files) is now only available on the create response. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202110-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202110-1.mdx new file mode 100644 index 0000000000..4cf6de42f6 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202110-1.mdx @@ -0,0 +1,37 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202110-1 (576) release. +--- + +# TFE Release v202110-1 (576) + +## Known Issues + +1. [February 8, 2022] This release includes a regression that removed default log rotation settings of Docker logs using the `json-file` logging driver (the default driver), affecting log rotation on installations with the new log forwarding feature disabled. If you do not enable the log forwarding feature on your installation, we recommend that you configure global log rotation settings to prevent disk space issues. For more information about configuring log rotation, refer to [Log Rotation](/terraform/enterprise/v202110-1/replicated/install/pre-install-checklist#log-rotation). This issue is fixed in v202201-2. + +## Installer Level Features + +1. RHEL 8 is now supported via the Replicated installer +1. RHEL 7.9 is now supported as an Alternative Worker Image + +## Application Level Features + +1. Added a clear filters link to private module search results + +## Application Level Bug Fixes + +1. Updated Vault to version 1.8.4 to fix an issue where database connections were not properly being removed from the connection pool. +1. Fixed an issue where fetching structured run output for a plan would result in a 500 status code. +1. Fixed dasherized keys within object output values on state version and state version output endpoints. For example, output maps containing key "my_output_key" would become "my-output-key" due to automatic jsonapi formatting. +1. Fixed "a.filter is not a function" error when expanding structured output plans containing sensitive set attributes and blocks. +1. Fixed hourly pricing for azurerm_managed_disk +1. Added support for plan json 1.0 +1. Fixed an issue where status timestamps were not populated correctly in configuration version API responses. +1. Fixed issue where the workspace UI showed elements only applicable to remote/agent execution modes when local execution mode was enabled. +1. Fixed Cost Estimation failure when looking up Elastisearch costs when using deprecated instance names ending in `elastisearch`. +1. Fixed issue where invalid UTF-8 characters in README can result in errors loading Workspaces. + +## Application Level Security Fixes + +1. Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202111-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202111-1.mdx new file mode 100644 index 0000000000..1888cce39a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202111-1.mdx @@ -0,0 +1,35 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202111-1 (582) release. +--- + +# TFE Release v202111-1 (582) + +## Known Issues + +1. [February 8, 2022] This release includes a regression that removed default log rotation settings of Docker logs using the `json-file` logging driver (the default driver), affecting log rotation on installations with the new log forwarding feature disabled. If you do not enable the log forwarding feature on your installation, we recommend that you configure global log rotation settings to prevent disk space issues. For more information about configuring log rotation, refer to [Log Rotation](/terraform/enterprise/v202111-1/replicated/install/pre-install-checklist#log-rotation). This issue is fixed in v202201-2. + +## APPLICATION LEVEL BREAKING CHANGES: + +- Certain application container images were updated to use Alpine 3.14 which has specific Docker, `runc`, and `libseccomp` version requirements. Please refer to [the Alpine 3.14 release notes](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.14.0#faccessat2) to determine if your installation meets these new requirements before upgrading. + +## APPLICATION LEVEL FEATURES: + +- Added support for terraform-json 0.13.0 +- Added increase github changed files probe for pull requests from 300 to 3000 +- Added a `tfe-admin list-nodes` command to list all active nodes in an active/active installation. + +## APPLICATION LEVEL BUG FIXES: + +- Fixed an issue where a workspace throws errors if it's locked by a team or user that is then deleted. +- Fixed an issue where all workspaces attached to a particular VCS repo would occasionally become unable to process webhooks. +- Fixed an issue where log forwarding was not configured with HTTP proxy environment variables. +- Fixed the Terraform version selector (in the workspace settings) for workspaces that use a custom version constraint (like `~> *0.5`). The selector will now show the constraint instead of the latest version. +- Fixed an issue where visible teams weren't visible in Terraform Enterprise due to an incorrect SQL join. +- Fixed issue where users could continue to select beta version of Terraform via API, even as betas are not allowed on the associated organization. + +## APPLICATION LEVEL SECURITY FIXES: + +- Updated the version of the internally-managed Vault server to \*8.4. +- Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202112-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202112-1.mdx new file mode 100644 index 0000000000..86e39f041c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202112-1.mdx @@ -0,0 +1,40 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202112-1 (588) release. +--- + +# TFE Release v202112-1 (588) + +## Known Issues + +1. [February 8, 2022] This release includes a regression that removed default log rotation settings of Docker logs using the `json-file` logging driver (the default driver), affecting log rotation on installations with the new log forwarding feature disabled. If you do not enable the log forwarding feature on your installation, we recommend that you configure global log rotation settings to prevent disk space issues. For more information about configuring log rotation, refer to [Log Rotation](/terraform/enterprise/v202112-1/replicated/install/pre-install-checklist#log-rotation). This issue is fixed in v202201-2. + +## UPCOMING DEPRECATION NOTICE: + +1. Effective April, 2022 there will be an update to Terraform Enterprise container names. This change may break container monitoring or custom tooling that identifies containers by name. More specific information regarding name changes will be made available in future release notes. + +## APPLICATION LEVEL FEATURES: + +1. SAML certificate signing and digest methods now are configurable +1. Added conditional pagination ability on GET indices for the following: SSH Keys, Parameters (on Policy Sets), Policy Checks (on Runs), Organizations, Policy Checks (on Runs), Oauth Clients, Oauth Tokens, Authentication (User) Tokens, Notification Configurations, Feature Sets, Feature Sets (on Organizations). If pagination parameters are not provided all results will be returned. +1. Added support for public provider and public module curation +1. Added support for tfc-agent 1.x series + +## APPLICATION LEVEL BUG FIXES: + +1. Fixed a bug where the `tfe-admin` command would set a configuration key to the value `''` instead of unsetting the configuration value. +1. Fixed an issue where custom CA certificates were not injected into the `tfe-fluent-bit` container. +1. Fixed an issue where Replicated snapshots were not executing for demo mode installations. +1. Fixed provider/module APIs to allow prefix searching, also fixes bug where providers were returned for unrelated (but member of) organizations. +1. Fixed structured run output to show a less verbose diff for json-encoded array fields +1. Added a fix to prevent the removal of the last owner of an organization via the API. It also gives precedence to returning an error if you remove the last owner over removing yourself (if you are an owner of the organization). Meaning that even though if you try to remove yourself (and you happen to be the only owner), the error that you'll receive is the same as if one tried to remove the only owner. You'll only receive the error message: `You cannot remove yourself from an organization you own` if you try to remove yourself and are not the only owner of an organization. Therefore the unit tests for "removing self as owner" had to be updated to include multiple owners in the organization. + +## APPLICATION LEVEL SECURITY FIXES: + +1. The Docker container running Nomad (`ptfe_nomad`) no longer runs with the `privileged` attribute. +1. Updated the version of the internally-managed Vault server to 1.9.0 +1. Updated the version of the internally-managed Nomad server to 1.1.6 +1. Updated `tfe-fluent-bit` to use Fluent Bit 1.8.10. +1. Updated `archivist` to address CVE in direct and indirect `jwt-go` dependency. +1. Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202112-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202112-2.mdx new file mode 100644 index 0000000000..885f0849e6 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2021/v202112-2.mdx @@ -0,0 +1,48 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the known issues, bug fixes, deprecations, breaking changes, features and security fixes for the v202112-2 (590) release. +--- + +# TFE Release v202112-2 (590) + +## Known Issues + +1. [February 8, 2022] This release includes a regression that removed default log rotation settings of Docker logs using the `json-file` logging driver (the default driver), affecting log rotation on installations with the new log forwarding feature disabled. If you do not enable the log forwarding feature on your installation, we recommend that you configure global log rotation settings to prevent disk space issues. For more information about configuring log rotation, refer to [Log Rotation](/terraform/enterprise/v202112-2/replicated/install/pre-install-checklist#log-rotation). This issue is fixed in v202201-2. + +## APPLICATION LEVEL BUG FIXES SINCE v202112-1: + +1. Updated the version of the terraform-registry that shipped with the v202112-1 release. + +## UPCOMING DEPRECATION NOTICE: + +1. Effective April, 2022 there will be an update to Terraform Enterprise container names. This change may break container monitoring or custom tooling that identifies containers by name. More specific information regarding name changes will be made available in future release notes. + +## APPLICATION LEVEL BREAKING CHANGES: + +None + +## APPLICATION LEVEL FEATURES: + +1. SAML certificate signing and digest methods now are configurable. +1. Added conditional pagination ability on GET indices for the following: SSH Keys, Parameters (on Policy Sets), Policy Checks (on Runs), Organizations, Policy Checks (on Runs), Oauth Clients, Oauth Tokens, Authentication (User) Tokens, Notification Configurations, Feature Sets, Feature Sets (on Organizations). All results are returned if pagination parameters are not provided. +1. Added support for public provider and public module curation. +1. Added support for tfc-agent 1.x series. + +## APPLICATION LEVEL BUG FIXES: + +1. Fixed a bug where the `tfe-admin` command would set a configuration key to the value `''` instead of unsetting the configuration value. +1. Fixed an issue where custom CA certificates were not injected into the `tfe-fluent-bit` container. +1. Fixed an issue where Replicated snapshots were not executing for demo mode installations. +1. Fixed provider/module APIs to allow prefix searching, also fixes bug where providers were returned for unrelated (but member of) organizations. +1. Fixed structured run output to show a less verbose diff for json-encoded array fields. +1. Added a fix to prevent the removal of the last owner of an organization via the API. It also gives precedence to returning an error if you are an organization owner and you remove the last owner over removing yourself. If you try to remove yourself and you are the only owner, the error is the same as if you tried to remove the only owner:`You cannot remove yourself from an organization you own`. Therefore, we updated the unit tests for "removing self as owner" to include multiple owners in the organization. + +## APPLICATION LEVEL SECURITY FIXES: + +1. The Docker container running Nomad (`ptfe_nomad`) no longer runs with the `privileged` attribute. +1. Updated the version of the internally-managed Vault server to 1.9.0. +1. Updated the version of the internally-managed Nomad server to 1.1.6. +1. Updated `tfe-fluent-bit` to use Fluent Bit 1.8.10. +1. Updated `archivist` to address CVE in direct and indirect `jwt-go` dependency. +1. Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/index.mdx new file mode 100644 index 0000000000..55c141269b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/index.mdx @@ -0,0 +1,34 @@ +--- +page_title: 2022 Releases - Terraform Enterprise +description: The 2022 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2022 + +Terraform Enterprise releases from 2022 are listed in the table below. + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI** | Sentinel | +| ------------------------------------------------------------ | ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| [v202212-2](/terraform/enterprise/releases/2022/v202212-2) | 667 | [2.54.0](https://release-notes.replicated.com/release-notes/2.54.0/) | [1.3.2](https://github.com/hashicorp/terraform/releases/tag/v1.3.2) | [0.18.13](https://docs.hashicorp.com/sentinel/changelog#0-18-13-october-31-2022) | +| [v202212-1](/terraform/enterprise/releases/2022/v202212-1) | 665 | [2.54.0](https://release-notes.replicated.com/release-notes/2.54.0/) | [1.3.2](https://github.com/hashicorp/terraform/releases/tag/v1.3.2) | [0.18.13](https://docs.hashicorp.com/sentinel/changelog#0-18-13-october-31-2022) | +| [v202211-1](/terraform/enterprise/releases/2022/v202211-1) | 660 | [2.54.0](https://release-notes.replicated.com/release-notes/2.54.0/) | [1.3.2](https://github.com/hashicorp/terraform/releases/tag/v1.3.2) | [0.18.13](https://docs.hashicorp.com/sentinel/changelog#0-18-13-october-31-2022) | +| [v202210-1](/terraform/enterprise/releases/2022/v202210-1) | 659 | [2.54.0](https://release-notes.replicated.com/release-notes/2.54.0/) | [1.2.9](https://github.com/hashicorp/terraform/releases/tag/v1.2.9) | [0.18.12](https://docs.hashicorp.com/sentinel/changelog#0-18-12-september-15-2022) | +| [v202209-2](/terraform/enterprise/releases/2022/v202209-2) | 655 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.7](https://github.com/hashicorp/terraform/releases/tag/v1.2.7) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | +| [v202209-1](/terraform/enterprise/releases/2022/v202209-1) | 654 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.7](https://github.com/hashicorp/terraform/releases/tag/v1.2.7) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | +| [v202208-3](/terraform/enterprise/releases/2022/v202208-3) | 652 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.4](https://github.com/hashicorp/terraform/releases/tag/v1.2.4) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | +| [v202208-2](/terraform/enterprise/releases/2022/v202208-2) | 651 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.4](https://github.com/hashicorp/terraform/releases/tag/v1.2.4) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | +| [v202208-1](/terraform/enterprise/releases/2022/v202208-1) | 647 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.4](https://github.com/hashicorp/terraform/releases/tag/v1.2.4) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | +| [v202207-2](/terraform/enterprise/releases/2022/v202207-2)\* | 642 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.4](https://github.com/hashicorp/terraform/releases/tag/v1.2.4) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | +| [v202207-1](/terraform/enterprise/releases/2022/v202207-1) | 641 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.4](https://github.com/hashicorp/terraform/releases/tag/v1.2.4) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | +| [v202206-1](/terraform/enterprise/releases/2022/v202206-1) | 636 | [2.53.6](https://release-notes.replicated.com/release-notes/2.53.6/) | [1.2.1](https://github.com/hashicorp/terraform/releases/tag/v1.2.1) | [0.18.10](https://docs.hashicorp.com/sentinel/changelog#0-18-10-may-20-2022) | +| [v202205-1](/terraform/enterprise/releases/2022/v202205-1) | 619 | [2.53.4](https://release-notes.replicated.com/release-notes/2.53.4/) | [1.1.9](https://github.com/hashicorp/terraform/releases/tag/v1.1.9) | [0.18.6](https://docs.hashicorp.com/sentinel/changelog#0-18-6-february-2-2022) | +| [v202204-2](/terraform/enterprise/releases/2022/v202204-2)\* | 610 | [2.53.4](https://release-notes.replicated.com/release-notes/2.53.4/) | [1.1.7](https://github.com/hashicorp/terraform/releases/tag/v1.1.7) | [0.18.6](https://docs.hashicorp.com/sentinel/changelog#0-18-6-february-2-2022) | +| [v202204-1](/terraform/enterprise/releases/2022/v202204-1) | 609 | [2.53.4](https://release-notes.replicated.com/release-notes/2.53.4/) | [1.1.7](https://github.com/hashicorp/terraform/releases/tag/v1.1.7) | [0.18.6](https://docs.hashicorp.com/sentinel/changelog#0-18-6-february-2-2022) | +| [v202203-1](/terraform/enterprise/releases/2022/v202203-1) | 607 | [2.53.4](https://release-notes.replicated.com/release-notes/2.53.4/) | [1.1.6](https://github.com/hashicorp/terraform/releases/tag/v1.1.6) | [0.18.6](https://docs.hashicorp.com/sentinel/changelog#0-18-6-february-2-2022) | +| [v202202-1](/terraform/enterprise/releases/2022/v202202-1) | 599 | [2.53.2](https://release-notes.replicated.com/release-notes/2.53.2/) | [1.1.5](https://github.com/hashicorp/terraform/releases/tag/v1.1.5) | [0.18.6](https://docs.hashicorp.com/sentinel/changelog#0-18-6-february-2-2022) | +| [v202201-2](/terraform/enterprise/releases/2022/v202201-2) | 595 | [2.53.2](https://release-notes.replicated.com/release-notes/2.53.2/) | [1.1.3](https://github.com/hashicorp/terraform/releases/tag/v1.1.3) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | +| [v202201-1](/terraform/enterprise/releases/2022/v202201-1) | 594 | [2.53.2](https://release-notes.replicated.com/release-notes/2.53.2/) | [1.1.3](https://github.com/hashicorp/terraform/releases/tag/v1.1.3) | [0.18.4](https://docs.hashicorp.com/sentinel/changelog#0-18-4-july-20-2021) | + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202201-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202201-1.mdx new file mode 100644 index 0000000000..ea508ffbe6 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202201-1.mdx @@ -0,0 +1,45 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202201-1 (594) release. +--- + +# Terraform Enterprise v202201-1 (594) + +## Deprecations + +1. If you are using Terraform CLI v1.1.0 or v1.1.1, please upgrade to the latest version as soon as possible. Terraform CLI v1.1.0 and v1.1.1 both have a bug where a failure to construct the apply-time graph can cause Terraform to incorrectly report success and save an empty state, effectively “forgetting” all existing infrastructure. Although configurations that already worked on previous releases should not encounter this problem, it’s possible that incorrect future configuration changes would trigger this behavior during the apply step. + +The Terraform Enterprise April 2022 release will: + +1. Remove the [demo operational mode](/terraform/enterprise/v202201-1/replicated/install/pre-install-checklist#operational-mode-decision), which is also known as the proof of concept (PoC) operational mode. The mounted disk operational mode will replace the demo operational mode for both non-production and production Terraform Enterprise environments. To check which mode your installation is using, run `replicatedctl app-config export --template '{{ .installation_type.Value }}'`. The value `poc` indicates that your installation is using the demo operational mode. The April 2022 release notes will contain more information about how to migrate. +1. Update the names of containers, which may break container monitoring or custom tooling that identifies containers by name. The April 2022 release notes will explain these name changes in more detail and provide a complete list of old and new container names. + +## Features + +1. The setting to [require site admins to enable two-factor authentication](/terraform/enterprise/application-administration/general#require-site-admins-to-enable-two-factor-authentication) now applies when SAML is enabled. +1. Install-specific values are now available in the API. The UI also uses a new API-driven page configuration during bootstrapping. +1. Users who are logged in can now view and manage their active sessions within their user settings. +1. The [CLI integration](/terraform/cli/cloud) is now available for using Terraform Enterprise from the command line. We recommend using this native integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. +1. Terraform versions 1.1.0 and 1.1.1 are now marked as deprecated. Deprecated versions cannot be selected in the workspace settings, but workspaces already using a deprecated version will display a warning. +1. Container resource usage metrics are now available in Prometheus format. +1. The private registry UI now displays a warning message for old versions of provider documentation with a link to the latest version. It also includes an **On this Page** outline for provider documentation that lets you navigate more quickly between sections. +1. Added an outline to the public provider documentation page +1. The [new `tfe-admin rotate-encryption-password` command](/terraform/enterprise/v202201-1/replicated/administration/infrastructure/admin-cli) rotates the encryption password on active/active installations of Terraform Enterprise. +1. A workspace's ID can now be copied from the workspace overview page. +1. New speculative attribute has been added to the [Configuration Versions API](/terraform/cloud-docs/api-docs/configuration-versions) response. +1. Add new option to allow teams that aren't the owner team to manage modules in the private registry. + +## Bug Fixes + +1. Obscured OAuth connection errors when connecting VCS providers, such as misconfigured scopes. +1. The Fluent Bit service did not respect lowercase versions of the `HTTP_PROXY` and `NO_PROXY` environment variables. +1. Terraform Enterprise installations using Replicated's `self-signed` TLS certificates returned 500 when fetching structured run output. +1. Resource names will not be mistakenly truncated in structured plan output. +1. Fixed a typo on the workspace variables page. + +## Security + +1. Removed an insecure reference to the initial admin user token from the `REGISTRY_BASE_URL` environment variable in the Registry service. +1. Updated Telegraf to version 1.12.1. +1. Updated InfluxDB to version 2.1.1. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202201-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202201-2.mdx new file mode 100644 index 0000000000..dc0445bf59 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202201-2.mdx @@ -0,0 +1,47 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202201-2 (595) release. +--- + +# Terraform Enterprise v202201-2 (595) + +## Changes Since v202201-1 + +1. Reintroduced the default log rotation settings for the `json-file` Docker logging driver, fixing a regression that was introduced in v202109-1 where container log files would grow unbounded and never rotate when the log forwarding feature was disabled. + +## Deprecations + +1. If you are using Terraform CLI v1.1.0 or v1.1.1, please upgrade to the latest version as soon as possible. Terraform CLI v1.1.0 and v1.1.1 both have a bug where a failure to construct the apply-time graph can cause Terraform to incorrectly report success and save an empty state, effectively “forgetting” all existing infrastructure. Although configurations that already worked on previous releases should not encounter this problem, it’s possible that incorrect future configuration changes would trigger this behavior during the apply step. + +The Terraform Enterprise April 2022 release will: + +1. Remove the [demo operational mode](/terraform/enterprise/v202201-2/replicated/install/pre-install-checklist#operational-mode-decision), which is also known as the proof of concept (PoC) operational mode. The mounted disk operational mode will replace the demo operational mode for both non-production and production Terraform Enterprise environments. To check which mode your installation is using, run `replicatedctl app-config export --template '{{ .installation_type.Value }}'`. The value `poc` indicates that your installation is using the demo operational mode. The April 2022 release notes will contain more information about how to migrate. +1. Update the names of containers, which may break container monitoring or custom tooling that identifies containers by name. The April 2022 release notes will explain these name changes in more detail and provide a complete list of old and new container names. + +## Features + +1. The setting to [require site admins to enable two-factor authentication](/terraform/enterprise/application-administration/general#require-site-admins-to-enable-two-factor-authentication) now applies when SAML is enabled. +1. Users who are logged in can now view and manage their active sessions within their user settings. +1. The [CLI integration](/terraform/cli/cloud) is now available for using Terraform Enterprise from the command line. We recommend using this native integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. +1. Terraform versions 1.1.0 and 1.1.1 are now marked as deprecated. Deprecated versions cannot be selected in the workspace settings, but workspaces already using a deprecated version will display a warning. +1. Container resource usage metrics are now available in Prometheus format. +1. The private registry UI now displays a warning message for old versions of provider documentation with a link to the latest version. It also includes an **On this Page** outline for provider documentation that lets you navigate more quickly between sections. +1. Added an outline to the public provider documentation page +1. The [new `tfe-admin rotate-encryption-password` command](/terraform/enterprise/v202201-2/replicated/administration/infrastructure/admin-cli) rotates the encryption password on active/active installations of Terraform Enterprise. +1. A workspace's ID can now be copied from the workspace overview page. +1. New speculative attribute has been added to the [Configuration Versions API](/terraform/cloud-docs/api-docs/configuration-versions) response. + +## Bug Fixes + +1. Obscured OAuth connection errors when connecting VCS providers, such as misconfigured scopes. +1. The Fluent Bit service did not respect lowercase versions of the `HTTP_PROXY` and `NO_PROXY` environment variables. +1. Terraform Enterprise installations using Replicated's `self-signed` TLS certificates returned 500 when fetching structured run output. +1. Resource names will not be mistakenly truncated in structured plan output. +1. Fixed a typo on the workspace variables page. + +## Security + +1. Removed an insecure reference to the initial admin user token from the `REGISTRY_BASE_URL` environment variable in the Registry service. +1. Updated Telegraf to version 1.12.1. +1. Updated InfluxDB to version 2.1.1. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202202-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202202-1.mdx new file mode 100644 index 0000000000..fe535e94ef --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202202-1.mdx @@ -0,0 +1,40 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202202-1 (599) release. +--- + +# Terraform Enterprise v202202-1 (599) + +## Deprecations + +The Terraform Enterprise April 2022 release will: + +1. Remove the [demo operational mode](/terraform/enterprise/v202202-1/replicated/install/pre-install-checklist#operational-mode-decision), which is also known as the proof of concept (PoC) operational mode. The mounted disk operational mode will replace the demo operational mode for both non-production and production Terraform Enterprise environments. To check which mode your installation is using, run `replicatedctl app-config export --template '{{ .installation_type.Value }}'`. The value `poc` indicates that your installation is using the demo operational mode. The April 2022 release notes will contain more information about how to migrate. +1. Update the names of containers, which may break container monitoring or custom tooling that identifies containers by name. The April 2022 release notes will explain these name changes in more detail and provide a complete list of old and new container names. +1. Change the default value of [`restrict_worker_metadata_access`](/terraform/enterprise/v202202-1/replicated/install/automated/automating-the-installer#restrict_worker_metadata_access) to 1 (true) instead of 0 (false). If you rely on the instance metadata endpoint (and make use of its instance profile), you must explicitly set the `restrict_worker_metadata_access` configuration flag in `replicated.conf` to 0. + +## Features + +1. Changed tag name restrictions to include letters, numbers, colons, hyphens, and underscores; and must begin and end with an alphanumeric character. +1. Added the ability to fuzzy find or find an exact match for Terraform versions using query parameters. + +## Bug Fixes + +1. Fixed rendering of multi-paragraph Terraform diagnostic messages. +2. Fixed run source UI "triggered from CLI" when using CLI cloud integration. +3. Fixed `deprecated-reason` to be null if tool version is un-deprecated in the Terraform Versions API. +4. Fixed slow initial UI load for users who belong to hundreds of organizations. +5. Fixed bug to disallow workspace from being renamed when a run has not completed. +6. Fixed a UI issue where newly created organization API tokens weren't shown when the previous one was recently deleted. +7. Updated Sentinel to 0.18.6 + +## Security + +1. Modified Terraform Enterprise application logging configuration to remediate inadvertent capture of HTTP request bodies (CVE-2022-25374). +1. Enables ACLs for the internally-managed Nomad service so that requests to Nomad must be authenticated. +1. Fixed rate limiting to be based on the AuthenticationToken instead of remote IP in some cases. +1. Updated the version of Rails to address CVE 2022-23633. +1. Updated the version of the internally-managed Vault server to 1.9.3. +1. Updated the version of the internally-managed Nomad server to 1.2.4. +1. Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202203-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202203-1.mdx new file mode 100644 index 0000000000..7946a36de9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202203-1.mdx @@ -0,0 +1,45 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202203-1 (607) release. +--- + +# Terraform Enterprise v202203-1 (607) + +## Known Issues + +1. [April 21, 2022] This release includes an issue with the `tfe-bootstrap` container being unable to negotiate the Docker API version causing the installation and upgrade of Terraform Enterprise to fail with `Error response from daemon: client version 1.41 is too new. Maximum supported API version is 1.40` affecting docker `v19.03.x` or older. This issue is fixed in `v202204-2`. +1. [May 10, 2022] This release includes an issue with Audit Log tagging, causing audit logs to no longer be tagged with the [Audit Log] prefix. This issue will be fixed in 'v202205-1'. + +## Breaking Changes + +The minimum required Replicated version is now 2.53.4. Airgap customers can visit this URL to download the latest Replicated version: [https://install.terraform.io/airgap/latest.tar.gz](https://install.terraform.io/airgap/latest.tar.gz). + +## Deprecations + +The Terraform Enterprise April 2022 release will: + +1. Remove the [demo operational mode](/terraform/enterprise/v202203-1/replicated/install/pre-install-checklist#operational-mode-decision), which is also known as the proof of concept (PoC) operational mode. The mounted disk operational mode will replace the demo operational mode for both non-production and production Terraform Enterprise environments. To check which mode your installation is using, run `replicatedctl app-config export --template '{{ .installation_type.Value }}'`. The value `poc` indicates that your installation is using the demo operational mode. The April 2022 release notes will contain more information about how to migrate. +1. Update the names of containers, which may break container monitoring or custom tooling that identifies containers by name. The April 2022 release notes will explain these name changes in more detail and provide a complete list of old and new container names. +1. Change the default value of [`restrict_worker_metadata_access`](/terraform/enterprise/v202203-1/replicated/install/automated/automating-the-installer#restrict_worker_metadata_access) to 1 (true) instead of 0 (false). If you rely on the instance metadata endpoint and make use of its instance profile, you must explicitly set the `restrict_worker_metadata_access` configuration flag in `replicated.conf` to 0. + +## Features + +1. Added the ability to [archive configuration versions](/terraform/cloud-docs/workspaces/configurations#archiving-configuration-versions) either automatically or manually in order to free up storage space and limit the amount of sensitive data stored in Terraform Enterprise. +1. Improved the performance and reliability when destroying large workspaces. +1. Added support to [publish private providers](/terraform/cloud-docs/registry/publish-providers) in the Terraform Cloud private registry. Once you have published a private provider through the API, members of your organization can search for it in the private registry UI and use it in configurations. +1. Added API endpoints to the Terraform Cloud API for [downloading configuration versions](/terraform/cloud-docs/api-docs/configuration-versions#download-configuration-files). A configuration version is a resource used to reference the uploaded configuration files that are associated with the Terraform runs. +1. Added [Variable Sets](/terraform/cloud-docs/api-docs/variable-sets) which let you reuse the same variables across multiple workspaces. For example, you could define a variable set of provider credentials and automatically apply it to all of the workspaces using that provider. . +1. Added html and/or plain-text email format support to all account-related emails that are sent to users on behalf of TFE. + +## Bug Fixes + +1. Fixed response code for JSON parse errors as parse failures should result in 400 Bad Request responses to clients. +1. Fixed API dasherizing state output keys when the top level output type is an array containing maps. +1. Fixed 500 error when fetching admin organization that does not exist. +1. Fixed syntax error when setting a Terraform variable to `null`. +1. Fixed Tag creation dates that are now displayed correctly. + +## Security + +Ongoing container updates to address reported vulnerabilities in underlying packages / dependencies, including OpenSSL-related [CVE-2022-0778](https://nvd.nist.gov/vuln/detail/CVE-2022-0778). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202204-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202204-1.mdx new file mode 100644 index 0000000000..8211261a95 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202204-1.mdx @@ -0,0 +1,48 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202201-1 (594) release. +--- + +# Terraform Enterprise v202204-1 (609) + +## Known Issues + +1. [April 21, 2022] This release includes an issue with the `tfe-bootstrap` container being unable to negotiate the Docker API version causing the installation and upgrade of Terraform Enterprise to fail with `Error response from daemon: client version 1.41 is too new. Maximum supported API version is 1.40` affecting docker `v19.03.x` or older. This issue is fixed in `v202204-2`. +2. [May 3, 2022] `tfe-admin health-check` fails with `sh: /root/ptfe-health-check: not found` after a change to the `ptfe_health_check` container Entrypoint to run the process as an unprivileged user under `/run/ptfe-health-check` but the `alias` was still referencing `/root/ptfe-health-check`. This issue will be fixed in `v202205-1`. +3. [May 10, 2022] This release includes an issue with Audit Log tagging, causing audit logs to no longer be tagged with the [Audit Log] prefix. This issue will be fixed in 'v202205-1'. + +## Breaking Changes + +1. The demo [operational mode](/terraform/enterprise/v202204-1/replicated/install/pre-install-checklist#operational-mode-decision) has been removed. If you are currently running demo mode, we strongly suggest that you upgrade to Terraform Enterprise v202204-1. To do this, you must [migrate your application data](/terraform/enterprise/v202307-1/admin/infrastructure/demo-to-disk-migration). + +The Terraform Enterprise May 2022 release will change the names of application containers from `ptfe_*` to `tfe-*` for product consistency. For example, `ptfe_nginx` will be changed to `tfe-nginx`. If you have downstream configuration (monitoring, log forwarding etc.) that references the older naming scheme, you will need to update container references to the new names. + +## Features + +1. Added a log storage memory limit to log forwarding. When the 128MB limit is reached, logs will be stored in a buffer on the filesystem until they can be forwarded. +1. Changed cost estimation so that it uses the [HTTP proxy settings](/terraform/enterprise/v202204-1/replicated/install/interactive/installer#proxy-usage) configured within Terraform Enterprise. +1. Added the ability to specify an ['SSO team ID'](/terraform/cloud-docs/users-teams-organizations/single-sign-on#team-names-and-sso-team-ids) for teams that Terraform Enterprise can use to map teams to non-human readable 'MemberOf' values in SAML assertions. +1. Updated display of download count metrics for modules in the private registry +1. Added an API endpoint to fetch a workspace's current state version outputs. Refer to [Show Current State Version Outputs For a Workspace](/terraform/cloud-docs/api-docs/state-version-outputs#show-current-state-version-outputs-for-a-workspace) for details. +1. Updated the default `json-file` log rotation settings for all containers in order to improve the performance of support bundle generation. + + | Previous Settings | New Settings | + | :----------------------------------: | :--------------------------------: | + | `max-size: 10m` and `max-file: 3` | `max-size: 8m` and `max-file: 4` | + | `max-size: 10m` and `max-file: 10` | `max-size: 32m` and `max-file: 4` | + | `max-size: 100m` and `max-file: 10` | `max-size: 64m` and `max-file: 8` | + | `max-size: 100m` and `max-file: 200` | `max-size: 50m` and `max-file: 20` | + +## Bug Fixes + +1. The [`iact_subnet_list` setting](/terraform/enterprise/v202204-1/replicated/install/automated/automating-the-installer#iact_subnet_list) now allows you to use `, ` to separate IPv4 addresses. +2. Fixed situation where occasionally you could not create a workspace after a workspace with the same name was deleted. +3. Fixed an issue causing configuration version tarballs downloaded through the API to have a non-human-readable filename and no file extension. +4. Fixed several issues with Terraform Cloud agent pools. + +## Security + +1. Added no-cache and no-store headers for some API responses that may contain sensitive data (2FA configuration, SSO configuration, and state versions). +1. Removed credentials from health-check endpoint for an internal service. +1. Adopted container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202204-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202204-2.mdx new file mode 100644 index 0000000000..28d713a56f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202204-2.mdx @@ -0,0 +1,51 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202204-2 (610) release. +--- + +# Terraform Enterprise v202204-2 (610 Required) + +## Changes Since v202204-1 + +The `tfe-bootstrap` container now automatically negotiates the Docker API version before making requests to the Docker API to prevent `Error response from daemon: client version 1.41 is too new. Maximum supported API version is 1.40` errors upon Terraform Enterprise installation or upgrade. + +## Known Issues + +1. [May 3, 2022] `tfe-admin health-check` fails with `sh: /root/ptfe-health-check: not found` after a change to the `ptfe_health_check` container Entrypoint to run the process as an unprivileged user under `/run/ptfe-health-check` but the `alias` was still referencing `/root/ptfe-health-check`. This issue will be fixed in `v202205-1`. +1. [May 10, 2022] This release includes an issue with Audit Log tagging, causing audit logs to no longer be tagged with the [Audit Log] prefix. This issue will be fixed in 'v202205-1'. + +## Breaking Changes + +1. The demo [operational mode](/terraform/enterprise/v202204-2/replicated/install/pre-install-checklist#operational-mode-decision) has been removed. If you are currently running demo mode, we strongly suggest that you upgrade to Terraform Enterprise v202204-1. To do this, you must [migrate your application data](/terraform/enterprise/v202307-1/admin/infrastructure/demo-to-disk-migration). + +The Terraform Enterprise May 2022 release will change the names of application containers from `ptfe_*` to `tfe-*` for product consistency. For example, `ptfe_nginx` will be changed to `tfe-nginx`. If you have downstream configuration (monitoring, log forwarding etc.) that references the older naming scheme, you will need to update container references to the new names. + +## Features + +1. Added a log storage memory limit to log forwarding. When the 128MB limit is reached, logs will be stored in a buffer on the filesystem until they can be forwarded. +1. Changed cost estimation so that it uses the [HTTP proxy settings](/terraform/enterprise/v202204-2/replicated/install/interactive/installer#proxy-usage) configured within Terraform Enterprise. +1. Added the ability to specify an ['SSO team ID'](/terraform/cloud-docs/users-teams-organizations/single-sign-on#team-names-and-sso-team-ids) for teams that Terraform Enterprise can use to map teams to non-human readable 'MemberOf' values in SAML assertions. +1. Updated display of download count metrics for modules in the private registry +1. Added an API endpoint to fetch a workspace's current state version outputs. Refer to [Show Current State Version Outputs For a Workspace](/terraform/cloud-docs/api-docs/state-version-outputs#show-current-state-version-outputs-for-a-workspace) for details. +1. Updated the default `json-file` log rotation settings for all containers in order to improve the performance of support bundle generation. + + | Previous Settings | New Settings | + | :----------------------------------: | :--------------------------------: | + | `max-size: 10m` and `max-file: 3` | `max-size: 8m` and `max-file: 4` | + | `max-size: 10m` and `max-file: 10` | `max-size: 32m` and `max-file: 4` | + | `max-size: 100m` and `max-file: 10` | `max-size: 64m` and `max-file: 8` | + | `max-size: 100m` and `max-file: 200` | `max-size: 50m` and `max-file: 20` | + +## Bug Fixes + +1. The [`iact_subnet_list` setting](/terraform/enterprise/v202204-2/replicated/install/automated/automating-the-installer#iact_subnet_list) now allows you to use `, ` to separate IPv4 addresses. +2. Fixed situation where occasionally you could not create a workspace after a workspace with the same name was deleted. +3. Fixed an issue causing configuration version tarballs downloaded through the API to have a non-human-readable filename and no file extension. +4. Fixed several issues with Terraform Cloud agent pools. + +## Security + +1. Added no-cache and no-store headers for some API responses that may contain sensitive data (2FA configuration, SSO configuration, and state versions). +1. Removed credentials from health-check endpoint for an internal service. +1. Adopted container updates to address reported vulnerabilities in underlying packages / dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202205-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202205-1.mdx new file mode 100644 index 0000000000..9d1831f0f0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202205-1.mdx @@ -0,0 +1,41 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202205-1 (619) release. +--- + +# Terraform Enterprise v202205-1 (619) + +## Known Issues + +1. External Vault users using the default Vault namespace will see the error `/usr/bin/vault-external-configure: line 37: VAULT_NAMESPACE: unbound variable` in the `tfe-vault` logs when attempting to start Terraform Enterprise. This error prevents Terraform Enterprise from starting. To resolve this, run `tfe-admin app-config -k extern_vault_namespace -v 'root'` and restart Terraform Enterprise. This does not affect External Vault users that use a custom Vault namespace. + +## Breaking Changes + +1. All container names now follow the same naming convention: `tfe-`. If you have tooling that identifies containers by name, make sure this tooling is updated to reflect the new naming convention. + +## Features + +1. Add option to de-register [inactive Agents](/terraform/cloud-docs/agents#agent-capacity-usage) through the **Organization Settings > Agents** UI. +2. Updated [Organization Memberships api](/terraform/cloud-docs/api-docs/organization-memberships#query-parameters) to add new `filter[email]` query parameter. +3. Updated [Teams api](/terraform/cloud-docs/api-docs/teams#query-parameters) to add new `filter[names]` query parameter. + +## Bug Fixes + +1. Fixed a bug where long words in a workspace readme were overflowing its column +2. Fixed potential issue when remembering 2FA logins with modern web browsers. +3. Changed logging to remove deprecation warnings related to :after_commit callbacks. This reduces noise in log output. +4. Fixed an issue with mock generation for nested attributes within a provider, which blocked Sentinel mocks from generating +5. Fixed application navigation to optimize for mobile use. +6. Fixed speculative, plan-only runs with incorrect run statuses that could prevent you from renaming workspaces. +7. Fixed a bug that broke retries for recoverable Git operations. +8. Fixed a bug that caused Git operations to retry unrecoverable authentication errors. +9. Improved agent dequeueing performance for large agent pools. +10. Changed Vault CLI commands to Vault API calls for token creation. This will prevent any Vault CLI/Server version mismatch errors. +11. Fixed issue where log tags such as "[Audit Log]" were not visible in logs. + +## Security + +1. Adopted container updates to address reported vulnerabilities in underlying packages / dependencies. +2. Updated the version of the internally-managed Vault server to 1.10.2. +3. Updated the version of the internally-managed Nomad server to 1.2.6. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202206-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202206-1.mdx new file mode 100644 index 0000000000..a36c95b2a8 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202206-1.mdx @@ -0,0 +1,38 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202206-1 (636) release. +--- + +# Terraform Enterprise v202206-1 (636) + +## Features + +1. Added [Run Task](/terraform/enterprise/workspaces/settings/run-tasks) functionality to Terraform Enterprise. +1. Added several new run options to simplify Terraform upgrades: [perform plan-only runs with an alternate Terraform version](/terraform/enterprise/run/ui#testing-terraform-upgrades-with-speculative-plans), re-try completed speculative plans with an alternate Terraform version, and use [empty apply runs](/terraform/enterprise/run/modes-and-options#allow-empty-apply) to upgrade your state without requiring config changes. +1. Added functionality to the [backup and restore API](/terraform/enterprise/v202206-1/replicated/administration/infrastructure/backup-restore) that lets Terraform Enterprise skip backing up the object storage data. +1. Added a warning in **Workspace > Settings > General** when you select a new Terraform version that is not recommended. +1. Updated the email template used when testing SMTP configuration. +1. Updated the email template used when sending VCS notifications. +1. Added support for [sending notifications to Microsoft Teams channels](/terraform/enterprise/workspaces/settings/notifications#microsoft-teams). +1. Terraform CLI versions up through 1.2.1 are now available. +1. Added a background task to backfill the `plan_only` column on the runs table. This is an internal cleanup task to support ongoing app improvements. No action is required. A future TFE release will perform any remaining work for this backfill as a normal database migration during the upgrade. + +## Bug Fixes + +1. Fixed SAML performance issue. Previously the SAML login performance would degrade significantly in installs with large amounts of Organizations and Teams. This release significantly improves the overall performance of SAML logins. +1. Fixed VCS Workspace creation not enabling "Automatic speculative plans" when enabled by the user. +1. [Structured run output](/terraform/enterprise/workspaces/settings#user-interface) will no longer throw the error `undefined is not an object` when objects are deleted. +1. Fixed a bug that was blocking users from cancelling runs in certain states. +1. Fixed a performance issue where requests to the `/workspaces` endpoint were taking longer than 3000ms. +1. Service Accounts will no longer be emailed when an Organization is deleted. +1. Fix 'Copy' button in two-factor settings for copying recovery codes. +1. Fixed an issue where upgrading Terraform Enterprise would overwrite existing Terraform CLI Versions. +1. Fixed an unbound variable error issue when `extern_vault_namespace` was unset. + +## Security + +1. Adopted container updates to address reported vulnerabilities in underlying packages / dependencies. +1. Updated go-getter version to protect against security vulnerabilities. +1. Updated ruby to 2.7.6, receiving a fix against a security vulnerability. +1. Updated Sentinel to 0.18.10 which included multiple security fixes for remote source installation. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202207-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202207-1.mdx new file mode 100644 index 0000000000..da44c9bbca --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202207-1.mdx @@ -0,0 +1,55 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202207-1 (641) release. +--- + +# Terraform Enterprise v202207-1 (641) + +## Known Issues + +1. Only applicable when using External Vault. You must update your [External Vault](/terraform/enterprise/v202207-1/replicated/install/vault) policy to use specific API paths instead of wildcard matching. Skipping this step prevents Terraform Enterprise from starting. + +## Highlights + +1. This release includes a data migration that will strengthen the association between a workspace and its current configuration version. This will improve query performance in many Terraform Enterprise workflows and reduce unnecessary `git clone` operations by keeping Terraform Enterprise from archiving the latest configuration version. **This migration will lengthen the upgrade process. You can expect it to take roughly 1 to 1.5 minutes per 10,000 workspaces.** +1. Using the new `azure_use_msi` and `azure_client_id` [settings](/terraform/enterprise/v202207-1/replicated/install/automated/automating-the-installer#available-settings), it is now possible to authenticate to Azure Blob Storage with a system-assigned or user-assigned Azure managed identity. +1. The `gcs_credentials` setting is now optional. Terraform Enterprise will attempt to authenticate to Google Blob Storage with the attached service account when the `gcs_credentials` variable is unset. +1. The internally-managed PostgreSQL server has been upgraded from PostgreSQL 12 to PostgreSQL 14. This change only affects mounted disk mode. It does not affect external services installations. The first time a Terraform Enterprise installation is upgraded to v202207-1, a program will be executed that will upgrade the PostgreSQL 12 data to PostgreSQL 14. This program takes a backup of the PostgreSQL data before upgrading. Regardless, operators should back up their Terraform Enterprise data before upgrading to Terraform Enterprise v202207-1. +1. External Services mode now officially supports PostgreSQL v13.x and v14.x. Follow the instructions to upgrade your PostgreSQL server: [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.html), [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-upgrade-using-dump-and-restore), [Google Cloud PostgreSQL](https://cloud.google.com/sql/docs/postgres/upgrade-major-db-version-inplace), or a [self-hosted PostgreSQL database](https://www.postgresql.org/docs/current/upgrading.html). +1. The `azure_endpoint` setting is now optional. The default Azure Blob Storage endpoint will be used when this setting is unset. If you have previously set a value for this setting and wish to use the default Azure Blob Storage endpoint, use `tfe-admin app-config -k azure_endpoint -v ''` to unset it to prevent a `dial tcp: lookup example_account.core.windows.net on 127.0.0.11:53: no such host"` error on application startup. + +-> **Note:** As of November 2, 2022, Terraform Enterprise fixed an issue that prevented the previously mentioned data migration from completing when workspaces had large amounts of configuration versions. This fix also improves performance. The digest of the new `tfe-atlas` container is: `sha256:0814d28867f5fa1b42a192237be94c8699f5af5102afcd8c10731636fc42e5b8` + +## Features + +1. When you create a new workspace in the UI from a version control repository, Terraform Enterprise scans its configuration files for Terraform variables and displays any that do not have a default value and are not defined in an existing global variable set. This lets you set values for these variables in preparation for your first Terraform run. If you skip this step, you can still create these variables manually later from within the workspace. +1. You can now [scope agent pools](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces) to specific workspaces from the Agent Pool settings page. This will allow you to protect sensitive workspaces by restricting which workspaces can target each agent pool. +1. The [Prometheus metrics endpoint](/terraform/enterprise/v202207-1/replicated/monitoring/monitoring#terraform-enterprise-metrics) now ships an additional metric `tfe_run_current_count`, which represents the current count of TFE runs in a given workspace, organization, and status. +1. Administrators can use [Admin Settings](/terraform/enterprise/api-docs/admin/settings) to set the maximum number of workspaces for any single organization. + +## Improvements + +1. When [listing workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces), you can now use the `exclude-tags` parameter to exclude workspaces with specific tags. +1. Any trailing `/` character will now be trimmed from the External Vault address (`extern_vault_addr`) to prevent making API requests to incorrect API paths. +1. API responses to the provider registry may now be shown in a different order than the previous release. + +## Bug Fixes + +1. Archivist will now return 500 status codes when Vault calls fail, and it is not a result of user error. Previously all Vault failures caused Archivist to return 400 status codes. +1. The edit button for workspace notification configurations now displays correctly instead of appearing as an unstyled link. +1. Logs no longer contain unhelpful `ruby_analytics` log messages. +1. The workspace variables settings page can now display all variable sets applied to a workspace, rather than just the first twenty. +1. Users may now authenticate via SAML in multiple concurrent sessions. Previously a bug would log out any existing sessions when authenticating via SAML. +1. Workspaces will no longer occasionally get stuck in a pending state when multiple runs are triggered at the same time. +1. Long variable keys on a workspace's variable page used to hide the corresponding sensitive and/or HCL tags. These tags now appear in the UI as expected. +1. VCS workspaces that end with a trailing `/` character will correctly render the `README.md` file if present. +1. Structured run output will no longer attempt to display a diff for data sources in the plan UI. This prevents a spurious error when data sources are used in a Terraform plan. +1. Changed ingress logic to avoid displaying unsupported GitHub repositories. +1. API rate limiting logic was modified to differentiate between the types of token being used for access, reducing reliance on the IP-based fallback rule which was causing problems in some shared environment use cases. + +## Security + +1. The [External Vault](/terraform/enterprise/v202207-1/replicated/install/vault) policy has been updated to use specific API paths instead of wildcard matching. +1. The version of the internally-managed Nomad server has been updated to 1.3.1. +1. Container updates have been adopted, addressing reported vulnerabilities (CVEs) in underlying packages / dependencies. This change bumps the version of Fluent Bit in `tfe-fluent-bit` to 1.9.5. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202207-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202207-2.mdx new file mode 100644 index 0000000000..491ec15ac4 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202207-2.mdx @@ -0,0 +1,59 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202207-2 (642) release. +--- + +# Terraform Enterprise v202207-2 (642 Required) + +## Changes Since v202207-1 + +1. For customers running a standalone TFE installation with metrics enabled, this release fixes a bug with metrics delivery. + +## Known Issues + +1. Only applicable when using External Vault. You must update your [External Vault](/terraform/enterprise/v202207-2/replicated/install/vault) policy to use specific API paths instead of wildcard matching. Skipping this step prevents Terraform Enterprise from starting. + +## Highlights + +1. This release includes a data migration that will strengthen the association between a workspace and its current configuration version. This will improve query performance in many Terraform Enterprise workflows and reduce unnecessary `git clone` operations by keeping Terraform Enterprise from archiving the latest configuration version. **This migration will lengthen the upgrade process. You can expect it to take roughly 1 to 1.5 minutes per 10,000 workspaces.** +1. Using the new `azure_use_msi` and `azure_client_id` [settings](/terraform/enterprise/v202207-2/replicated/install/automated/automating-the-installer#available-settings), it is now possible to authenticate to Azure Blob Storage with a system-assigned or user-assigned Azure managed identity. +1. The `gcs_credentials` setting is now optional. Terraform Enterprise will attempt to authenticate to Google Blob Storage with the attached service account when the `gcs_credentials` variable is unset. +1. The internally-managed PostgreSQL server has been upgraded from PostgreSQL 12 to PostgreSQL 14. This change only affects mounted disk mode. It does not affect external services installations. The first time a Terraform Enterprise installation is upgraded to v202207-1, a program will be executed that will upgrade the PostgreSQL 12 data to PostgreSQL 14. This program takes a backup of the PostgreSQL data before upgrading. Regardless, operators should back up their Terraform Enterprise data before upgrading to Terraform Enterprise v202207-1. +1. External Services mode now officially supports PostgreSQL v13.x and v14.x. Follow the instructions to upgrade your PostgreSQL server: [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.html), [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-upgrade-using-dump-and-restore), [Google Cloud PostgreSQL](https://cloud.google.com/sql/docs/postgres/upgrade-major-db-version-inplace), or a [self-hosted PostgreSQL database](https://www.postgresql.org/docs/current/upgrading.html). +1. The `azure_endpoint` setting is now optional. The default Azure Blob Storage endpoint will be used when this setting is unset. If you have previously set a value for this setting and wish to use the default Azure Blob Storage endpoint, use `tfe-admin app-config -k azure_endpoint -v ''` to unset it to prevent a `dial tcp: lookup example_account.core.windows.net on 127.0.0.11:53: no such host"` error on application startup. + +-> **Note:** As of November 2, 2022, Terraform Enterprise fixed an issue that prevented the previously mentioned data migration from completing when workspaces had large amounts of configuration versions. This fix also improves performance. The digest of the new `tfe-atlas` container is: `sha256:0814d28867f5fa1b42a192237be94c8699f5af5102afcd8c10731636fc42e5b8` + +## Features + +1. When you create a new workspace in the UI from a version control repository, Terraform Enterprise scans its configuration files for Terraform variables and displays any that do not have a default value and are not defined in an existing global variable set. This lets you set values for these variables in preparation for your first Terraform run. If you skip this step, you can still create these variables manually later from within the workspace. +1. You can now [scope agent pools](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces) to specific workspaces from the Agent Pool settings page. This will allow you to protect sensitive workspaces by restricting which workspaces can target each agent pool. +1. The [Prometheus metrics endpoint](/terraform/enterprise/v202207-2/replicated/monitoring/monitoring#terraform-enterprise-metrics) now ships an additional metric `tfe_run_current_count`, which represents the current count of TFE runs in a given workspace, organization, and status. +1. Administrators can use [Admin Settings](/terraform/enterprise/api-docs/admin/settings) to set the maximum number of workspaces for any single organization. + +## Improvements + +1. When [listing workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces), you can now use the `exclude-tags` parameter to exclude workspaces with specific tags. +1. Any trailing `/` character will now be trimmed from the External Vault address (`extern_vault_addr`) to prevent making API requests to incorrect API paths. +1. API responses to the provider registry may now be shown in a different order than the previous release. + +## Bug Fixes + +1. Archivist will now return 500 status codes when Vault calls fail, and it is not a result of user error. Previously all Vault failures caused Archivist to return 400 status codes. +1. The edit button for workspace notification configurations now displays correctly instead of appearing as an unstyled link. +1. Logs no longer contain unhelpful `ruby_analytics` log messages. +1. The workspace variables settings page can now display all variable sets applied to a workspace, rather than just the first twenty. +1. Users may now authenticate via SAML in multiple concurrent sessions. Previously a bug would log out any existing sessions when authenticating via SAML. +1. Workspaces will no longer occasionally get stuck in a pending state when multiple runs are triggered at the same time. +1. Long variable keys on a workspace's variable page used to hide the corresponding sensitive and/or HCL tags. These tags now appear in the UI as expected. +1. VCS workspaces that end with a trailing `/` character will correctly render the `README.md` file if present. +1. Structured run output will no longer attempt to display a diff for data sources in the plan UI. This prevents a spurious error when data sources are used in a Terraform plan. +1. Changed ingress logic to avoid displaying unsupported GitHub repositories. +1. API rate limiting logic was modified to differentiate between the types of token being used for access, reducing reliance on the IP-based fallback rule which was causing problems in some shared environment use cases. + +## Security + +1. The [External Vault](/terraform/enterprise/v202207-2/replicated/install/vault) policy has been updated to use specific API paths instead of wildcard matching. +1. The version of the internally-managed Nomad server has been updated to 1.3.1. +1. Container updates have been adopted, addressing reported vulnerabilities (CVEs) in underlying packages / dependencies. This change bumps the version of Fluent Bit in `tfe-fluent-bit` to 1.9.5. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-1.mdx new file mode 100644 index 0000000000..a86cfccabe --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-1.mdx @@ -0,0 +1,35 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202208-1 (647) release. +--- + +# Terraform Enterprise v202208-1 (647) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues + +1. Database migrations will fail during startup when using PostgreSQL 10 and 11. This is fixed in v202208-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Features + +1. You can enable workload identity at either the workspace level or the variable set level by specifying a value for the `TFC_WORKLOAD_IDENTITY_AUDIENCE` [environment variable](/terraform/cloud-docs/workspaces/variables). Enabling workload identity generates a token, stored in the `TFC_WORKLOAD_IDENTITY_TOKEN` variable in your run environment. You can use the token to authenticate cloud providers instead of relying on long-lived credentials in Terraform Enterprise. Contact your HashiCorp representative for details and setup instructions. + +## Improvements + +1. Terraform bundles now attempt to determine the version of the `terraform` binary to more efficiently extract Terraform plugins. +1. When you create a VCS-backed workspace and configure variables in the UI, Terraform Enterprise now validates variable values for the correct type (boolean, string, number, map, list). If the type is incorrect, Terraform Enterprise displays an error message. This helps you configure the required variables for the first run. +1. When generating Sentinel mocks, the `full_name` field will now be included in provider configuration blocks. The value of this field is the entire fully-qualified provider name including hostname and namespace, providing alignment with Terraform CLI json output. + +## Bug Fixes + +1. The Run UI now renders one-line errors in plans or applies correctly, so you do not need to download raw text logs to review the output. +1. The Module Registry Protocol endpoint `/v1/modules/{namespace}/{name}/{provider}/versions` no longer errors when handling modules with a large number of versions. + +## Security + +1. Reading outputs through the Workspaces API's includable relationships now requires permission to read the state version outputs of the workspace. +1. Terraform Enterprise updated `rails` to 6.1.6. This change addresses reported vulnerabilities (CVEs). +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-2.mdx new file mode 100644 index 0000000000..9a37347f68 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-2.mdx @@ -0,0 +1,37 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202208-2 (651) release. +--- + +# Terraform Enterprise v202208-2 (651) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Changes Since v202208-1 + +1. Database migrations will now successfully complete on startup when running PostgreSQL 10 and 11. + +## Known Issues +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Features + +1. You can enable workload identity at either the workspace level or the variable set level by specifying a value for the `TFC_WORKLOAD_IDENTITY_AUDIENCE` [environment variable](/terraform/cloud-docs/workspaces/variables). Enabling workload identity generates a token, stored in the `TFC_WORKLOAD_IDENTITY_TOKEN` variable in your run environment. You can use the token to authenticate cloud providers instead of relying on long-lived credentials in Terraform Enterprise. Contact your HashiCorp representative for details and setup instructions. + +## Improvements + +1. Terraform bundles now attempt to determine the version of the `terraform` binary to more efficiently extract Terraform plugins. +1. When you create a VCS-backed workspace and configure variables in the UI, Terraform Enterprise now validates variable values for the correct type (boolean, string, number, map, list). If the type is incorrect, Terraform Enterprise displays an error message. This helps you configure the required variables for the first run. +1. When generating Sentinel mocks, the `full_name` field will now be included in provider configuration blocks. The value of this field is the entire fully-qualified provider name including hostname and namespace, providing alignment with Terraform CLI json output. + +## Bug Fixes + +1. The Run UI now renders one-line errors in plans or applies correctly, so you do not need to download raw text logs to review the output. +1. The Module Registry Protocol endpoint `/v1/modules/{namespace}/{name}/{provider}/versions` no longer errors when handling modules with a large number of versions. + +## Security + +1. Reading outputs through the Workspaces API's includable relationships now requires permission to read the state version outputs of the workspace. +1. Terraform Enterprise updated `rails` to 6.1.6. This change addresses reported vulnerabilities (CVEs). +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-3.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-3.mdx new file mode 100644 index 0000000000..20f96dad8f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202208-3.mdx @@ -0,0 +1,41 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202208-3 (652) release. +--- + +# Terraform Enterprise v202208-3 (652) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Changes Since v202208-2 + +1. Fixed a regression where run pipeline metrics would not appear in the Prometheus endpoint. + +## Changes Since v202208-1 + +1. Database migrations will now successfully complete on startup when running PostgreSQL 10 and 11. + +## Known Issues +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Features + +1. You can enable workload identity at either the workspace level or the variable set level by specifying a value for the `TFC_WORKLOAD_IDENTITY_AUDIENCE` [environment variable](/terraform/cloud-docs/workspaces/variables). Enabling workload identity generates a token, stored in the `TFC_WORKLOAD_IDENTITY_TOKEN` variable in your run environment. You can use the token to authenticate cloud providers instead of relying on long-lived credentials in Terraform Enterprise. Contact your HashiCorp representative for details and setup instructions. + +## Improvements + +1. Terraform bundles now attempt to determine the version of the `terraform` binary to more efficiently extract Terraform plugins. +1. When you create a VCS-backed workspace and configure variables in the UI, Terraform Enterprise now validates variable values for the correct type (boolean, string, number, map, list). If the type is incorrect, Terraform Enterprise displays an error message. This helps you configure the required variables for the first run. +1. When generating Sentinel mocks, the `full_name` field will now be included in provider configuration blocks. The value of this field is the entire fully-qualified provider name including hostname and namespace, providing alignment with Terraform CLI json output. + +## Bug Fixes + +1. The Run UI now renders one-line errors in plans or applies correctly, so you do not need to download raw text logs to review the output. +1. The Module Registry Protocol endpoint `/v1/modules/{namespace}/{name}/{provider}/versions` no longer errors when handling modules with a large number of versions. + +## Security + +1. Reading outputs through the Workspaces API's includable relationships now requires permission to read the state version outputs of the workspace. +1. Terraform Enterprise updated `rails` to 6.1.6. This change addresses reported vulnerabilities (CVEs). +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202209-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202209-1.mdx new file mode 100644 index 0000000000..0bf678ffe2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202209-1.mdx @@ -0,0 +1,48 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202209-1 (654) release. +--- + +# Terraform Enterprise v202209-1 (654) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues + +1. The newly introduced data migration contains database logic that is incompatible with PostgreSQL 10.x. You must upgrade your PostgreSQL server to version 11.x or later in order to run Terraform Enterprise v202209-1. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Breaking Changes + +1. [Speculative Plans](/terraform/enterprise/run/remote-operations#speculative-plans) are now enabled by default for workspaces using the version control workflow. Because of this change, the UI default now matches the defaults in the [Workspace API](/terraform/enterprise/api-docs/workspaces) and the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/workspace#speculative_enabled). + +## Highlights + +1. Terraform Enterprise now enforces the following background migrations and runs them synchronously during upgrades: `DeleteDuplicateHostedFilesForConfigVersions`, `BackfillArchivistObjectStorageDeletionRequests`, `DeleteSoftDeletedHostedFiles`, and `BackfillHostedFileStorageDeletionRequests`. These will block the upgrade process until they are complete. If you have a large installation and are concerned about this blocking the upgrade process you can stop at `v202208-3` and wait until `tfe-admin background-migration-status-all` returns a `0` exit code before proceeding further. +2. This release contains a data migration that will lengthen the upgrade process. You can expect it to take roughly 1-2 minutes for 5,000 organizations, 2-4 minutes for 10,000 organizations. + +## Features + +1. Each HTML template can now produce a text-only version of the email. +1. You can now set a workspace to automatically trigger Terraform runs when you publish a [git tag with a specific format](/terraform/enterprise/workspaces/settings/vcs#trigger-runs-when-a-git-tag-is-published) + +## Improvements + +1. The `PeriodicHostedFileGCWorker` and `DeleteArchivistObjectsWorker` jobs have been removed as they have been superseded by the `StorageDeletionWorker`. The `StorageDeletionWorker` deletes both hosted files and archivist objects more efficiently than the aforementioned jobs, making them unnecessary. +1. The State Version Outputs API has new attributes that store and reveal extra type information. You can now include the attribute `json-state-outputs` when creating a [state version](/terraform/enterprise/api-docs/state-versions#create-a-state-version). These values describe the output values of the state. You can also view the `detailed-type` attribute when viewing [state version outputs](/terraform/enterprise/api-docs/state-version-outputs#list-state-version-outputs), which refines the output with the precise Terraform type. + +## Bug Fixes + +1. Plan output parsing error is now more descriptive and supports a max json nesting of 400. +1. The structured run output diagnostic renderer displays more context for errors caused when you incorrectly call a function or when a pre or postcondition fails. The additional context for incorrect function invocation is only available for runs using Terraform version 1.3.0+. +1. We increased the time between when you delete a workspace and when we actually remove that workspace from the Terraform Enterprise database. This buffer period reduces the likelihood of race conditions when you delete a workspace containing lot of data. +1. When you delete a workspace in admin view, Terraform Enterprise now properly cancels the deletion when you select **Cancel** or close the dialog. +1. Improved explanations for Runs that were not automatically applied in workspaces with auto-approve enabled +1. The workspace destruction process is more reliable. Previously, when you deleted a workspace, Terraform Enterprise would sometimes fail to clean up all associated records. This failure sometimes caused confusion in the UI or caused Terraform Enterprise to consume resources longer than necessary. We made several improvements to address these issues. +1. Build agents and the Terraform build worker now ignore `TF_TOKEN_hostname` workspace variables that match the Terraform Enterprise hostname. These processes must authenticate to the Terraform Enterprise host using a run-specific authentication token. + +## Security + +1. This release updates the internally-managed Nomad server to version 1.3.4. +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202209-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202209-2.mdx new file mode 100644 index 0000000000..a98793e767 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202209-2.mdx @@ -0,0 +1,53 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202209-2 (655) release. +--- + +# Terraform Enterprise v202209-2 (655) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Changes Since v202209-1 + +1. Updated the internally-managed Vault policy to fix a `403 permission denied` error that prevented Terraform Enterprise from starting. + +## Known Issues + +1. The newly introduced data migration contains database logic that is incompatible with PostgreSQL 10.x. You must upgrade your PostgreSQL server to version 11.x or later in order to run Terraform Enterprise v202209-1. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Breaking Changes + +1. [Speculative Plans](/terraform/enterprise/run/remote-operations#speculative-plans) are now enabled by default for workspaces using the version control workflow. Because of this change, the UI default now matches the defaults in the [Workspace API](/terraform/enterprise/api-docs/workspaces) and the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/workspace#speculative_enabled). + +## Highlights + +1. Terraform Enterprise now enforces the following background migrations and runs them synchronously during upgrades: `DeleteDuplicateHostedFilesForConfigVersions`, `BackfillArchivistObjectStorageDeletionRequests`, `DeleteSoftDeletedHostedFiles`, and `BackfillHostedFileStorageDeletionRequests`. These will block the upgrade process until they are complete. If you have a large installation and are concerned about this blocking the upgrade process you can stop at `v202208-3` and wait until `tfe-admin background-migration-status-all` returns a `0` exit code before proceeding further. +1. This release contains a data migration that will lengthen the upgrade process. You can expect it to take roughly 1-2 minutes for 5,000 organizations, 2-4 minutes for 10,000 organizations. + + +## Features + +1. Each HTML template can now produce a text-only version of the email. +1. You can now set a workspace to automatically trigger Terraform runs when you publish a [git tag with a specific format](/terraform/enterprise/workspaces/settings/vcs#trigger-runs-when-a-git-tag-is-published) + +## Improvements + +1. The `PeriodicHostedFileGCWorker` and `DeleteArchivistObjectsWorker` jobs have been removed as they have been superseded by the `StorageDeletionWorker`. The `StorageDeletionWorker` deletes both hosted files and archivist objects more efficiently than the aforementioned jobs, making them unnecessary. +1. The State Version Outputs API has new attributes that store and reveal extra type information. You can now include the attribute `json-state-outputs` when creating a [state version](/terraform/enterprise/api-docs/state-versions#create-a-state-version). These values describe the output values of the state. You can also view the `detailed-type` attribute when viewing [state version outputs](/terraform/enterprise/api-docs/state-version-outputs#list-state-version-outputs), which refines the output with the precise Terraform type. + +## Bug Fixes + +1. Plan output parsing error is now more descriptive and supports a max json nesting of 400. +1. The structured run output diagnostic renderer displays more context for errors caused when you incorrectly call a function or when a pre or postcondition fails. The additional context for incorrect function invocation is only available for runs using Terraform version 1.3.0+. +1. We increased the time between when you delete a workspace and when we actually remove that workspace from the Terraform Enterprise database. This buffer period reduces the likelihood of race conditions when you delete a workspace containing lot of data. +1. When you delete a workspace in admin view, Terraform Enterprise now properly cancels the deletion when you select **Cancel** or close the dialog. +1. Improved explanations for Runs that were not automatically applied in workspaces with auto-approve enabled +1. The workspace destruction process is more reliable. Previously, when you deleted a workspace, Terraform Enterprise would sometimes fail to clean up all associated records. This failure sometimes caused confusion in the UI or caused Terraform Enterprise to consume resources longer than necessary. We made several improvements to address these issues. +1. Build agents and the Terraform build worker now ignore `TF_TOKEN_hostname` workspace variables that match the Terraform Enterprise hostname. These processes must authenticate to the Terraform Enterprise host using a run-specific authentication token. + +## Security + +1. This release updates the internally-managed Nomad server to version 1.3.4. +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202210-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202210-1.mdx new file mode 100644 index 0000000000..f22e3d701b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202210-1.mdx @@ -0,0 +1,58 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202210-1 (659) release. +--- + +# Terraform Enterprise v202210-1 (659) + +_Updated October 6, 2022_ + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Breaking Changes + +PostgreSQL server version 10 is no longer supported. If you are using an external PostgreSQL server with your Terraform Enterprise installation, you must upgrade to PostgreSQL server version 11 or later. However, we recommend upgrading to PostgreSQL server version 12 or later instead of PostgreSQL server version 11 since PostgreSQL server version 11 is deprecated. + +## Deprecations + +The following operating systems are deprecated, and will no longer be supported following the February Terraform Enterprise release (v202302-1). + +- Debian 8, 9 +- Ubuntu 14.04, 16.04 +- Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 + +The following PostgreSQL server versions are deprecated, and will no longer be supported following the February Terraform Enterprise release (v202302-1). + +- PostgreSQL 11 + +## Highlights + +1. This release contains a data migration that will lengthen the upgrade process. You can expect it to take roughly 1-2 minutes per 5,000 organizations. + +## Features + +1. You can now query by `name` and `email` when listing organizations using the [Organizations API](/terraform/cloud-docs/api-docs/organizations) endpoint. +1. You can now forcefully cancel policy checks on Terraform runs. + +## Improvements + +1. The [State Versions API](/terraform/cloud-docs/api-docs/state-versions#create-a-state-version) endpoint now accepts an optional `json-state` attribute when creating a state version. The `json-state` attribute is a Base64 encoded string containing the JSON format of the Terraform state file as expressed by `terraform show -json`. Runs using Terraform version 1.3+ will set this `json-state` attribute when creating a state version which can then be used by Terraform Enterprise integrations. + +## Bug Fixes + +1. When comparing JSON-encoded arrays with null values, the structured run output now displays the resource diff under the `plan finished` tab without errors. Previously, the structured run output contained errors for `aws_ecs_task_definition` resources with empty `container_definitions`. +1. Resource status badges are now vertically aligned in structured run output, regardless of the length of the resource name. +1. The UI now displays output from apply operations without depending on the actual values of sensitive data. Previously, run logs contained the plaintext value of sensitive outputs. Terraform version 1.4+ omits all sensitive output values in the downloaded run logs. +1. Enabling workload identity in workspaces with policy checks no longer causes runs to stop responding and eventually fail. +1. Run tasks now timeout after 10 minutes, preventing runs from staying in a pending state indefinitely. +1. Workspace outputs of type `object` with keys containing dashes will no longer be `null` when you view them using `terraform output`. +1. Terraform Enterprise provides more informative errors when it cannot archive a configuration version. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. +1. Fluent Bit is updated to version 1.9.7. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202211-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202211-1.mdx new file mode 100644 index 0000000000..af08fef358 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202211-1.mdx @@ -0,0 +1,51 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202211-1 (660) release. +--- + +# Terraform Enterprise v202211-1 (660) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +The following operating systems are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + +- Debian 8, 9 +- Ubuntu 14.04, 16.04 +- Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 + +The following PostgreSQL server versions are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + +- PostgreSQL 11 + +## Features + +1. The [Workspaces API](/terraform/enterprise/api-docs/workspaces) now supports two options for deleting workspaces: safe delete and force delete. Safe delete prevents you from accidentally deleting locked workspaces or workspaces that are managing resources. When you delete a workspace with resources, Terraform can no longer track or manage the remaining infrastructure. Organization owners can force delete locked workspaces with resources, and they can choose whether to give workspace administrators force delete permissions. + +## Improvements + +1. The API produces a clearer error message when you try to assign the same team to a workspace more than once. +1. The SQL query to retrieve organization owners is optimized to improve the latency for requests using the owners team API token. +1. You can now re-authorize OAuth clients without losing workspace VCS connections. + +## Bug Fixes + +1. The post plan completed run state will now trigger a needs attention notification when a Post Plan Task is configured. +1. The run summary now shows a warning when advisory policies fail instead of a passing icon. +1. The plan UI output no longer suggests sensitive config values exist when they are not defined. +1. The Workspace Outputs API no longer replaces dashes with underscores for keys in the `detailed-type` field. This bug prevented Terraform CLI 1.2+ from displaying output values when their names contained dashes. +1. Terraform Enterprise now delays populating outputs from state versions until it can parse the state file outside of the create request. This helps avoid long request times and timeouts when Terraform produces thousands of outputs. +1. Workspace resources that have multiple instances now store their resource address using the correct index key. These resources previously used an integer index that didn't match the resource address in Terraform state. In particular, this affects resources created with the `for_each` meta-argument. +1. The UI no longer incorrectly tags variables from variable sets as **Overwritten**. When navigating between workspaces that share a variable set, the UI used to occasionally tag variables as **Overwritten** when there were no local overrides in the current workspace. +1. Exceptions in Sidekiq workers cannot log sensitive run variables. + +## Security + +1. Updated Fluent Bit to version 1.9.9. +1. The `tfe-fluent-bit` container now uses a [Distroless](https://github.com/GoogleContainerTools/distroless) image, which improves security by eliminating unnecessary packages. +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202212-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202212-1.mdx new file mode 100644 index 0000000000..2815e77666 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202212-1.mdx @@ -0,0 +1,62 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202212-1 (665) release. +--- + +# Terraform Enterprise v202212-1 (665) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues + +1. The Certificate Authority (CA) bundle is not injected into the `tfe-task-worker` container, resulting in x509 errors in Sentinel policies when connecting to HTTPS endpoints. This is fixed in Terraform Enterprise v202212-2. + +1. The logging for some services (tfe-atlas and tfe-sidekiq) are set to `debug` causing an increase in logging output. This is corrected in v202301-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +The following operating systems are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + +- Debian 8, 9 +- Ubuntu 14.04, 16.04 +- Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 + +The following PostgreSQL server versions are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + +- PostgreSQL 11 + +## Highlights + +1. The `tfe-nomad` container has been removed and replaced with a new `tfe-task-worker` container. The `tfe-task-worker` container is now responsible for running `sentinel`, `cost-estimation`, and `plan-exporter` tasks. Logs for these tasks can now be found in the `tfe-task-worker` container logs. This change is part of a larger effort to refresh the architecture of Terraform Enterprise, improve performance and reliability of runs, and support future application-level features. +1. A new `tfe-atlas-ui` container has been added to serve the Terraform Enterprise frontend and static assets. +1. Terraform Enterprise no longer starts when connected to an [unsupported PostgreSQL server version](/terraform/enterprise/v202212-1/replicated/requirements/data-storage/postgres-requirements) to prevent potential database incompatibility issues when upgrading. The entry `PostgreSQL version X does not meet PostgreSQL version requirements` will appear in the logs. +1. Terraform Enterprise now supports [Run tasks in the Pre-plan and Pre-apply](/terraform/cloud-docs/workspaces/settings/run-tasks#associating-run-tasks-with-a-workspace) stages of a run. Run tasks are custom integrations that can send run data to external services. They can either produce warnings or stop runs, depending on your workspace settings. + +## Features + +1. For Terraform versions 1.2+, Terraform Enterprise hides data sources reads in the plan UI by default. Use the filter checkbox to show them when necessary. +1. The [List Workspaces API endpoint](/terraform/enterprise/api-docs/workspaces#list-workspaces) now supports wildcard matching. For example, searching with `search[wildcard-name]=*-prod` returns all workspaces ending in `-prod`. + +## Improvements + +1. Improved the performance of a data migration added in Terraform Enterprise v202207-1 for installations with large amounts of configuration versions. +1. You no longer need to confirm plans with no infrastructure changes that Terraform created with the `allow-empty-apply` option. You may want to use this option when you [upgrade your workspace's state](/terraform/enterprise/workspaces/state#upgrading-state) to a new Terraform version. +1. The users administration page now displays a warning next to accounts with an unconfirmed email address. + +## Bug Fixes + +1. Terraform Enterprise no longer occasionally fails to save outputs associated with a new state. +1. The `tfe-registry-worker` now consistently cleans up the temp disk space that it used during module ingress. +1. Using the the API to create a module version beginning with `v` no longer prevents the registry from displaying other module versions. Versions like `v1.0.3` previously caused failures. +1. You can now download Sentinel mocks for older Terraform runs. +1. When you cancel a Terraform run during the apply process, Terraform Enterprise now displays the resource state as `Unknown`. Previously, the UI showed a message incorrectly implying that Terraform was still attempting to complete the apply. +1. The VCS provider settings no longer displays a blank page for organizations with large numbers of VCS providers. +1. Failed attempts to reauthorize VCS providers no longer prevent new reauthorization workflows. +1. OAuth clients that the `tfe-provider` is managing can no longer start VCS provider reauthorization. +1. Public GitHub avatars will no longer be used for private provider logos when the namespace for the private provider matches a GitHub username. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202212-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202212-2.mdx new file mode 100644 index 0000000000..0a267c238b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2022/v202212-2.mdx @@ -0,0 +1,66 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202212-2 (667) release. +--- + +# Terraform Enterprise v202212-2 (667) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues + +1. VCS-managed Sentinel policies will fail with `"getent": executable file not found in $PATH`. This will be fixed in Terraform Enterprise v202301-1. + +1. The logging for some services (tfe-atlas and tfe-sidekiq) are set to `debug` causing an increase in logging output. This is corrected in v202301-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Changes Since v202212-1 + +1. The Certificate Authority (CA) bundle is now injected into the `tfe-task-worker` container, fixing an issue where Sentinel policies would return x509 errors when connecting to HTTPS endpoints. + +## Deprecations + +The following operating systems are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + +- Debian 8, 9 +- Ubuntu 14.04, 16.04 +- Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 + +The following PostgreSQL server versions are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + +- PostgreSQL 11 + +## Highlights + +1. The `tfe-nomad` container has been removed and replaced with a new `tfe-task-worker` container. The `tfe-task-worker` container is now responsible for running `sentinel`, `cost-estimation`, and `plan-exporter` tasks. Logs for these tasks can now be found in the `tfe-task-worker` container logs. This change is part of a larger effort to refresh the architecture of Terraform Enterprise, improve performance and reliability of runs, and support future application-level features. +1. A new `tfe-atlas-ui` container has been added to serve the Terraform Enterprise frontend and static assets. +1. Terraform Enterprise no longer starts when connected to an [unsupported PostgreSQL server version](/terraform/enterprise/v202212-2/replicated/requirements/data-storage/postgres-requirements) to prevent potential database incompatibility issues when upgrading. The entry `PostgreSQL version X does not meet PostgreSQL version requirements` will appear in the logs. +1. Terraform Enterprise now supports [Run tasks in the Pre-plan and Pre-apply](/terraform/cloud-docs/workspaces/settings/run-tasks#associating-run-tasks-with-a-workspace) stages of a run. Run tasks are custom integrations that can send run data to external services. They can either produce warnings or stop runs, depending on your workspace settings. + +## Features + +1. For Terraform versions 1.2+, Terraform Enterprise hides data sources reads in the plan UI by default. Use the filter checkbox to show them when necessary. +1. The [List Workspaces API endpoint](/terraform/enterprise/api-docs/workspaces#list-workspaces) now supports wildcard matching. For example, searching with `search[wildcard-name]=*-prod` returns all workspaces ending in `-prod`. + +## Improvements + +1. Improved the performance of a data migration added in Terraform Enterprise v202207-1 for installations with large amounts of configuration versions. +1. You no longer need to confirm plans with no infrastructure changes that Terraform created with the `allow-empty-apply` option. You may want to use this option when you [upgrade your workspace's state](/terraform/enterprise/workspaces/state#upgrading-state) to a new Terraform version. +1. The users administration page now displays a warning next to accounts with an unconfirmed email address. + +## Bug Fixes + +1. Terraform Enterprise no longer occasionally fails to save outputs associated with a new state. +1. The `tfe-registry-worker` now consistently cleans up the temp disk space that it used during module ingress. +1. Using the the API to create a module version beginning with `v` no longer prevents the registry from displaying other module versions. Versions like `v1.0.3` previously caused failures. +1. You can now download Sentinel mocks for older Terraform runs. +1. When you cancel a Terraform run during the apply process, Terraform Enterprise now displays the resource state as `Unknown`. Previously, the UI showed a message incorrectly implying that Terraform was still attempting to complete the apply. +1. The VCS provider settings no longer displays a blank page for organizations with large numbers of VCS providers. +1. Failed attempts to reauthorize VCS providers no longer prevent new reauthorization workflows. +1. OAuth clients that the `tfe-provider` is managing can no longer start VCS provider reauthorization. +1. Public GitHub avatars will no longer be used for private provider logos when the namespace for the private provider matches a GitHub username. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/index.mdx new file mode 100644 index 0000000000..0d4919dec5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/index.mdx @@ -0,0 +1,67 @@ +--- +page_title: 2023 Releases - Terraform Enterprise +description: The 2023 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2023 + +Terraform Enterprise releases from 2023 are listed in the table below. + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively in a Kubernetes environment. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Tested Kubernetes Versions (EKS, AKS, GKE) | Helm Chart Version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | ------------------ | +| [v202312-1](/terraform/enterprise/releases/2023/v202312-1) | [1.6.4](https://github.com/hashicorp/terraform/releases/tag/v1.6.4) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [1.24](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.24.9](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.27.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202311-1](/terraform/enterprise/releases/2023/v202311-1) | [1.6.2](https://github.com/hashicorp/terraform/releases/tag/v1.6.2) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [1.24](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.24.9](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.27.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.0) | +| [v202310-1](/terraform/enterprise/releases/2023/v202310-1) | [1.6.0](https://github.com/hashicorp/terraform/releases/tag/v1.6.0) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [1.24](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.24.9](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.27.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.0.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.0.0) | +| [v202309-1](/terraform/enterprise/releases/2023/v202309-1) | [1.5.6](https://github.com/hashicorp/terraform/releases/tag/v1.5.6) | [0.22.1](https://docs.hashicorp.com/sentinel/changelog#0-22-1-june-22-2023) | [1.24](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.24.9](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.27.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.0.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.0.0) | + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Docker. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Recommended Docker Compose version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | +| [v202312-1](/terraform/enterprise/releases/2023/v202312-1) | [1.6.4](https://github.com/hashicorp/terraform/releases/tag/v1.6.4) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202311-1](/terraform/enterprise/releases/2023/v202311-1) | [1.6.2](https://github.com/hashicorp/terraform/releases/tag/v1.6.2) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202310-1](/terraform/enterprise/releases/2023/v202310-1) | [1.6.0](https://github.com/hashicorp/terraform/releases/tag/v1.6.0) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202309-1](/terraform/enterprise/releases/2023/v202309-1) | [1.5.6](https://github.com/hashicorp/terraform/releases/tag/v1.5.6) | [0.22.1](https://docs.hashicorp.com/sentinel/changelog#0-22-1-june-22-2023) | [V2](https://docs.docker.com/compose/migrate/) | + + + + +Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in **March 2025**. HashiCorp will support this release until April 1, 2026. + +To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by **November 2024**. For more information, refer to [Terraform Enterprise deployment overview](/terraform/enterprise/deploy) or contact your HashiCorp account representative. + +Below is a list of the most recent Terraform Enterprise releases for the replicated deployment method. [Learn more about Replicated](/terraform/enterprise/deploy/replicated). + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI\** | Sentinel | +| ------------------------------------------------------------ | ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [v202312-1](/terraform/enterprise/releases/2023/v202312-1) | 745 | [2.56.1](https://release-notes.replicated.com/release-notes/2.56.1/) | [1.6.4](https://github.com/hashicorp/terraform/releases/tag/v1.6.4) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | +| [v202311-1](/terraform/enterprise/releases/2023/v202311-1) | 742 | [2.56.1](https://release-notes.replicated.com/release-notes/2.56.1/) | [1.6.2](https://github.com/hashicorp/terraform/releases/tag/v1.6.2) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | +| [v202310-1](/terraform/enterprise/releases/2023/v202310-1) | 741 | [2.56.0](https://release-notes.replicated.com/release-notes/2.56.0/) | [1.6.0](https://github.com/hashicorp/terraform/releases/tag/v1.6.0) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | +| [v202309-1](/terraform/enterprise/releases/2023/v202309-1) | 733 | [2.56.0](https://release-notes.replicated.com/release-notes/2.56.0/) | [1.5.6](https://github.com/hashicorp/terraform/releases/tag/v1.5.6) | [0.22.1](https://docs.hashicorp.com/sentinel/changelog#0-22-1-june-22-2023) | +| [v202308-1](/terraform/enterprise/releases/2023/v202308-1) | 725 | [2.56.0](https://release-notes.replicated.com/release-notes/2.56.0/) | [1.5.4](https://github.com/hashicorp/terraform/releases/tag/v1.5.4) | [0.22.1](https://docs.hashicorp.com/sentinel/changelog#0-22-1-june-22-2023) | +| [v202307-1](/terraform/enterprise/releases/2023/v202307-1) | 722 | [2.55.0](https://release-notes.replicated.com/release-notes/2.55.0/) | [1.5.1](https://github.com/hashicorp/terraform/releases/tag/v1.5.1) | [0.22.1](https://docs.hashicorp.com/sentinel/changelog#0-22-1-june-22-2023) | +| [v202306-1](/terraform/enterprise/releases/2023/v202306-1) | 713 | [2.55.0](https://release-notes.replicated.com/release-notes/2.55.0/) | [1.4.6](https://github.com/hashicorp/terraform/releases/tag/v1.4.6) | [0.22.0](https://docs.hashicorp.com/sentinel/changelog#0-22-0-may-31-2023) | +| [v202305-2](/terraform/enterprise/releases/2023/v202305-2) | 706 | [2.55.0](https://release-notes.replicated.com/release-notes/2.55.0/) | [1.4.6](https://github.com/hashicorp/terraform/releases/tag/v1.4.6) | [0.21.0](https://docs.hashicorp.com/sentinel/changelog#0-21-0-march-8-2023) | +| [v202305-1](/terraform/enterprise/releases/2023/v202305-1) | 703 | [2.55.0](https://release-notes.replicated.com/release-notes/2.55.0/) | [1.4.6](https://github.com/hashicorp/terraform/releases/tag/v1.4.6) | [0.21.0](https://docs.hashicorp.com/sentinel/changelog#0-21-0-march-8-2023) | +| [v202304-1](/terraform/enterprise/releases/2023/v202304-1)\* | 692 | [2.54.1](https://release-notes.replicated.com/release-notes/2.54.1/) | [1.4.4](https://github.com/hashicorp/terraform/releases/tag/v1.4.4) | [0.21.0](https://docs.hashicorp.com/sentinel/changelog#0-21-0-march-8-2023) | +| [v202303-1](/terraform/enterprise/releases/2023/v202303-1) | 688 | [2.54.1](https://release-notes.replicated.com/release-notes/2.54.1/) | [1.4.0](https://github.com/hashicorp/terraform/releases/tag/v1.4.0) | [0.20.0](https://docs.hashicorp.com/sentinel/changelog#0-20-0-february-16-2023) | +| [v202302-1](/terraform/enterprise/releases/2023/v202302-1) | 681 | [2.54.1](https://release-notes.replicated.com/release-notes/2.54.1/) | [1.3.8](https://github.com/hashicorp/terraform/releases/tag/v1.3.8) | [0.19.5](https://docs.hashicorp.com/sentinel/v0.19.x/changelog#0-19-5-february-9-2023) | +| [v202301-2](/terraform/enterprise/releases/2023/v202301-2) | 676 | [2.54.0](https://release-notes.replicated.com/release-notes/2.54.0/) | [1.3.7](https://github.com/hashicorp/terraform/releases/tag/v1.3.7) | [0.18.13](https://docs.hashicorp.com/sentinel/changelog#0-18-13-october-31-2022) | +| [v202301-1](/terraform/enterprise/releases/2023/v202301-1) | 675 | [2.54.0](https://release-notes.replicated.com/release-notes/2.54.0/) | [1.3.7](https://github.com/hashicorp/terraform/releases/tag/v1.3.7) | [0.18.13](https://docs.hashicorp.com/sentinel/changelog#0-18-13-october-31-2022) | +| [v202207-2](/terraform/enterprise/releases/2022/v202207-2)\* | 642 | [2.53.7](https://release-notes.replicated.com/release-notes/2.53.7/) | [1.2.4](https://github.com/hashicorp/terraform/releases/tag/v1.2.4) | [0.18.11](https://docs.hashicorp.com/sentinel/changelog#0-18-11-june-8-2022) | + + + + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202301-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202301-1.mdx new file mode 100644 index 0000000000..2a6cfa61cb --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202301-1.mdx @@ -0,0 +1,80 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202301-1 (675) release. +--- + +# Terraform Enterprise v202301-1 (675) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues + +1. The logging for some services (tfe-atlas and tfe-sidekiq) are set to `debug` causing an increase in logging output. This is corrected in v202301-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +- The following operating systems are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + - Debian 8, 9 + - Ubuntu 14.04, 16.04 + - Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 +- The following PostgreSQL server versions are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + - PostgreSQL 11 +- Terraform Build Workers are deprecated and will be removed in v202305-1; the base image responsible for executing Terraform runs is changing to tfc-agent. If you are using an alternative worker image, you must migrate to a new image using the tfc-agent base image before v202305-1. If you are not using an alternative worker image no action is required, you will automatically migrate to the new base image in v202302-1 or higher. For more information, refer to the Custom Agent Image migration [guide](/terraform/enterprise/v202301-1/replicated/administration/infrastructure/worker-to-agent-migration). + +## Breaking Changes + +1. The "Manage Policies" Organization Permission has been modified to remove excessive access to resources. **This is a breaking change** as Policy Managers may now require additional permission to perform tasks. As per the API Stability Policy, backwards incompatible changes may be necessary to protect your security. The following permissions changes have been made: + + - Policy Managers will no longer be able to read State Versions. + - Policy Managers will no longer be able to read State Version Outputs. + - Policy Managers will no longer be able to read Assessments and Assessment Results. + - Policy Managers will no longer be able to read variables and variable sets which are not Policy Set parameters. + - Policy Managers will no longer be able to create Workspace Comments. + - Policy Managers will no longer be able to read Workspace Resources. + - Policy Managers will no longer be able to read Run Triggers. + - Policy Managers will no longer be able to list Configuration Versions. + - Policy Managers will no longer be able to read Workspace Notification Configurations. + - Policy Managers will be able to read OAuth Client and OAuth Tokens. Without this change, policy managers cannot add VCS backed Policy Sets. + - Policy Managers be able to list runs in a workspace. + +## Highlights + +1. We've streamlined and updated the Graphical User Interface's navigation menus to match Terraform Cloud. You can now navigate the app from the side menu instead of using a mix of the top menu, side menu, and tabs. + +## Features + +1. You can now share providers in your private registries across many organizations, just like you can for modules. Choose if you want to share all modules and providers, only modules, or only providers. No more publishing and republishing providers in separate organizations. +1. New workspace state feature allows rollback to an older version of state. This can be used to fall back to a known good version of state following an event such as an unfinished upgrade or unwanted state manipulation. The operation does not remove prior states and does not change underlying infrastructure. + +## Improvements + +1. Terraform Enterprise will show a summary of the resources to be created, modified, and destroyed near the prompt to apply or discard a run. It highlights failed policy checks, destroyed resources, or failed run tasks more prominently, so users have better visibility into whether they are applying a potentially dangerous plan. +1. The organization access permissions are now more consistently formatted and have clearer permission subheadings. +1. Rare instances of workspaces failing to delete now have more informative logging. +1. The private registry will now validate providers are supported by the Terraform SDK. +1. Workspace API responses now include a `self-html` link, which is a browsable URL for the workspace. +1. The private registry will no longer accept identifiers for prerelease versions of modules or providers that do not conform to [the SemVer standard](https://semver.org/#spec-item-9). Attempts to publish a version with an invalid prerelease version identifier (e.g. `1.2.3.4` or `1.2.3-beta!`) will now fail. +1. Diagnostics results view for Structured Run Output can now be collapsed. +1. When a workspace set to Structured Run Output mode has a successful apply, the Outputs view will be expanded by default. + +## Bug Fixes + +1. Database schemas are now created every time the application is started, fixing an issue where the `task_worker` schema was missing upon upgrade. +1. Sentinel policy runs no longer fail with the error `exec: "getent": executable file not found in $PATH`. +1. The `tfe-admin support-bundle` command no longer fails uploading support bundles to Google Cloud Storage. +1. Attempts to update a user's email to an invalid value will now be rejected when the update it attempted, not during confirmation of the new email. +1. Old workspaces which have undergone a destroy run before Oct 3, 2023 may now be safe-deleted. +1. Provider binary's name is now validated at the time of publishing, fixing an issue where a provider could be made unusable if the filename contained invalid characters. +1. Sentinel will no longer assume that unknown values are boolean, fixing an issue for some Terraform plan variations. +1. The teams/organization-memberships endpoint no longer gives a 500 response error when you try to delete a member whose user record could not be found. +1. For modules or providers with prerelease versions (e.g. `v1.2.3-preview-2`), the registry's internal sorting was sometimes incorrect. This could result in the wrong version being presented as the "latest" version in some API responses. As new versions of a module or provider are added to the database, they will now be resorted correctly. +1. State version output type validations no longer cause exceptions due to optional attribute bugs in Terraform. +1. State version parser service omits detailed type information in callback responses for V1-V3 statefiles since detailed types are V4 statefile specific. This prevents validation exceptions in TFC when state version outputs are processed and stored. +1. When creating multiple workspaces simultaneously with the same tags, each workspace will be created successfully with respective tags attached to it, instead of sometimes returning a `404 Not Found` error. +1. VCS runs will no longer trigger on discarded workspaces. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202301-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202301-2.mdx new file mode 100644 index 0000000000..79bd87832d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202301-2.mdx @@ -0,0 +1,84 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202301-2 (676) release. +--- + +# Terraform Enterprise v202301-2 (676) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Changes Since v202301-1 + +1. Logs for tfe-atlas, tfe-atlas-ui and tfe-sidekiq will no longer contain debug logs. This change fixes the issue introduced in v202212-1 where the log level was set to `debug`, causing a large increase in the log size for these services. + +## Known Issues + +1. Saving boolean `false` variable values causes 500 errors. This has been fixed in [`v202303-1`](/terraform/enterprise/releases/2023/v202303-1#bug-fixes). +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +- The following operating systems are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + - Debian 8, 9 + - Ubuntu 14.04, 16.04 + - Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 +- The following PostgreSQL server versions are deprecated, and Terraform Enterprise will stop supporting them following the February 2023 release (v202302-1). + - PostgreSQL 11 +- Terraform Build Workers are deprecated and will be removed in v202305-1; the base image responsible for executing Terraform runs is changing to tfc-agent. If you are using an alternative worker image, you must migrate to a new image using the tfc-agent base image before v202305-1. If you are not using an alternative worker image no action is required, you will automatically migrate to the new base image in v202302-1 or higher. For more information, refer to the Custom Agent Image migration [guide](/terraform/enterprise/v202301-2/replicated/administration/infrastructure/worker-to-agent-migration). + +## Breaking Changes + +1. The "Manage Policies" Organization Permission has been modified to remove excessive access to resources. **This is a breaking change** as Policy Managers may now require additional permission to perform tasks. As per the API Stability Policy, backwards incompatible changes may be necessary to protect your security. The following permissions changes have been made: + + - Policy Managers will no longer be able to read State Versions. + - Policy Managers will no longer be able to read State Version Outputs. + - Policy Managers will no longer be able to read Assessments and Assessment Results. + - Policy Managers will no longer be able to read variables and variable sets which are not Policy Set parameters. + - Policy Managers will no longer be able to create Workspace Comments. + - Policy Managers will no longer be able to read Workspace Resources. + - Policy Managers will no longer be able to read Run Triggers. + - Policy Managers will no longer be able to list Configuration Versions. + - Policy Managers will no longer be able to read Workspace Notification Configurations. + - Policy Managers will be able to read OAuth Client and OAuth Tokens. Without this change, policy managers cannot add VCS backed Policy Sets. + - Policy Managers be able to list runs in a workspace. + +## Highlights + +1. We've streamlined and updated the Graphical User Interface's navigation menus to match Terraform Cloud. You can now navigate the app from the side menu instead of using a mix of the top menu, side menu, and tabs. + +## Features + +1. You can now share providers in your private registries across many organizations, just like you can for modules. Choose if you want to share all modules and providers, only modules, or only providers. No more publishing and republishing providers in separate organizations. +1. New workspace state feature allows rollback to an older version of state. This can be used to fall back to a known good version of state following an event such as an unfinished upgrade or unwanted state manipulation. The operation does not remove prior states and does not change underlying infrastructure. + +## Improvements + +1. Terraform Enterprise will show a summary of the resources to be created, modified, and destroyed near the prompt to apply or discard a run. It highlights failed policy checks, destroyed resources, or failed run tasks more prominently, so users have better visibility into whether they are applying a potentially dangerous plan. +1. The organization access permissions are now more consistently formatted and have clearer permission subheadings. +1. Rare instances of workspaces failing to delete now have more informative logging. +1. The private registry will now validate providers are supported by the Terraform SDK. +1. Workspace API responses now include a `self-html` link, which is a browsable URL for the workspace. +1. The private registry will no longer accept identifiers for prerelease versions of modules or providers that do not conform to [the SemVer standard](https://semver.org/#spec-item-9). Attempts to publish a version with an invalid prerelease version identifier (e.g. `1.2.3.4` or `1.2.3-beta!`) will now fail. +1. Diagnostics results view for Structured Run Output can now be collapsed. +1. When a workspace set to Structured Run Output mode has a successful apply, the Outputs view will be expanded by default. + +## Bug Fixes + +1. Database schemas are now created every time the application is started, fixing an issue where the `task_worker` schema was missing upon upgrade. +1. Sentinel policy runs no longer fail with the error `exec: "getent": executable file not found in $PATH`. +1. The `tfe-admin support-bundle` command no longer fails uploading support bundles to Google Cloud Storage. +1. Attempts to update a user's email to an invalid value will now be rejected when the update it attempted, not during confirmation of the new email. +1. Old workspaces which have undergone a destroy run before Oct 3, 2023 may now be safe-deleted. +1. Provider binary's name is now validated at the time of publishing, fixing an issue where a provider could be made unusable if the filename contained invalid characters. +1. Sentinel will no longer assume that unknown values are boolean, fixing an issue for some Terraform plan variations. +1. The teams/organization-memberships endpoint no longer gives a 500 response error when you try to delete a member whose user record could not be found. +1. For modules or providers with prerelease versions (e.g. `v1.2.3-preview-2`), the registry's internal sorting was sometimes incorrect. This could result in the wrong version being presented as the "latest" version in some API responses. As new versions of a module or provider are added to the database, they will now be resorted correctly. +1. State version output type validations no longer cause exceptions due to optional attribute bugs in Terraform. +1. State version parser service omits detailed type information in callback responses for V1-V3 statefiles since detailed types are V4 statefile specific. This prevents validation exceptions in TFC when state version outputs are processed and stored. +1. When creating multiple workspaces simultaneously with the same tags, each workspace will be created successfully with respective tags attached to it, instead of sometimes returning a `404 Not Found` error. +1. VCS runs will no longer trigger on discarded workspaces. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202302-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202302-1.mdx new file mode 100644 index 0000000000..2eec8b7a45 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202302-1.mdx @@ -0,0 +1,70 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202302-1 (681) release. +--- + +# Terraform Enterprise v202302-1 (681) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Known Issues + +1. When you assign a team the `manage-workspaces` permission through the API the team is also explicitly granted the `read-workspaces` permission, which provides a subset of the functionality. However, using the API to revoke just the `manage-workspace` permission does **not** revoke the `read-workspaces` permission. This means that existing automation (including the `tfe` provider) for revoking the `manage-workspaces` permission will leave the team with the `read-workspaces` permission, whereas previously the team would be left with no workspace access at the organization level. This will be resolved in upcoming versions of Terraform Enterprise and the `tfe` provider. +1. Terraform runs remain queued indefinitely when using the `agent` run pipeline mode unless the **Enable agents functionality** checkbox is checked in the [admin interface](/terraform/enterprise/application-administration/admin-access). The logs for `tfe-task-worker` will show `[ERROR] core: Unexpected HTTP response code: method=POST url=https://terraform.example.com/api/agent/register status=404`. This is resolved in Terraform Enterprise v202303-1. +1. [April 6, 2023] The `tfe-admin node-drain` command does not currently work when the `run_pipeline_mode` configuration setting is set to `agent`. See the notes under the _Highlights_ section for more details regarding this setting. This issue is fixed in the v202305-1 release. +1. Saving boolean `false` variable values causes 500 errors. This has been fixed in [`v202303-1`](/terraform/enterprise/releases/2023/v202303-1#bug-fixes). +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Breaking Changes + +1. The sub claim for workload identity tokens now contains project information. You must [update the trust relationship](https://support.hashicorp.com/hc/en-us/articles/13138701895699-Updating-Workload-Identity-for-Projects) on your cloud provider to expect project information in this claim. + +## Deprecations and End of Support + +The following operating systems are no longer supported: + +- Debian 8, 9 +- Ubuntu 14.04, 16.04 +- Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 + +The following PostgreSQL server versions are no longer supported: + +- 11 + +Terraform Build Workers are deprecated and will be removed in Terraform Enterprise v202305-1. The base image responsible for executing Terraform runs is now `hashicorp/tfc-agent`. If you are using an alternative worker image, you must migrate to a new image using `hashicorp/tfc-agent` as its base image before Terraform Enterprise v202305-1. If you are not using an alternative worker image then you will automatically migrate to the new base image and no futher action is required. For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202302-1/replicated/administration/infrastructure/worker-to-agent-migration). + +[Updated: August 2023] The `aws` CLI utility is no longer included in the base image. If the `aws` CLI utility is needed in your custom agent image, you may install it by following the [AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202302-1/replicated/administration/infrastructure/worker-to-agent-migration). + +## Highlights + +1. Three components of the run pipeline, `tfe-build-worker`, `tfe-build-manager`, and `tfe-rabbitmq`, have been replaced with `tfe-task-worker`, a local implementation of [tfc-agent](https://hub.docker.com/r/hashicorp/tfc-agent). If you are using an alternative worker image, you will need to [migrate to a new image](/terraform/enterprise/v202302-1/replicated/administration/infrastructure/worker-to-agent-migration) before enabling the new run pipeline. If you are not using an alternative worker image then you will automatically migrate to the new run pipeline. The new run pipeline can be manually enabled by setting the `run_pipeline_mode` configuration setting to `agent` or disabled by setting the `run_pipeline_mode` configuration setting to `legacy`. Monitoring integrations may need to be updated if you are monitoring `tfe-build-worker`, `tfe-build-manager`, or `tfe-rabbitmq`. +1. Workspaces can now be grouped into projects. Projects help users organize and centrally manage their workspaces at scale while providing more granular permissions to a subset of workspaces. Each project has a separate permissions set that you can use to grant teams access to all workspaces in the project. [This blog post](https://www.hashicorp.com/blog/terraform-cloud-adds-projects-to-organize-workspaces-at-scale) covers projects in more detail. +1. The [GitHub App Integration](/terraform/enterprise/application-administration/github-app-integration) is now available for Terraform Enterprise. Connect your Workspaces, Policy Sets, & Registry Modules without creating an Organization OAuth Client. Requires site-admin access to setup. +1. Red Hat Enterprise Linux 8.7 is now supported. + +## Features + +1. Sentinel Policy Checks now run Sentinel 0.19.5, introducing support for static imports, allowing supporting data to be imported into a policy. +1. Organization owners can now assign teams read access to workspaces and projects within a particular organization. +1. Added Terraform versions 1.3.8 and 1.4.0-beta1. +1. Structured run output is enabled for CLI-driven workspaces when using Terraform CLI version 1.4.0-beta1 or later. +1. The VCS Events page is now available for Terraform Enterprise. The page displays VCS-related messages such as when processing fails due to a duplicate webhook. + +## Improvements + +1. `tfe-admin support-bundle` will now upload support bundles to object storage for both external services and active/active installations. +1. The name of the VCS repository is now included in 400 request errors when an error occurs while creating a VCS workspace. +1. When a webhook is received that contains the same commit SHA of a previously processed webhook that created a non-speculative run, it will no longer be processed and a message will be logged to the VCS Events page. + +## Bug Fixes + +1. Previously, a bug was introduced which changed the flash message design. The design bug is now fixed. +1. The sidebar items of the workspace overview page are now displayed with proper height when the workspace has a long README. +1. The workspace overview page now displays its sidebar component visibly in small screens. +1. Terraform plans no longer error when generating Sentinel mock files. + +## Security + +1. The endpoint used for confirming a user's email address now has a tighter rate limit to reduce risk of email spam attacks. +1. The endpoint used for sending "Forgot Password" emails now has a rate limit to reduce risk of email spam attacks. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202303-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202303-1.mdx new file mode 100644 index 0000000000..3a73bd9639 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202303-1.mdx @@ -0,0 +1,72 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202303-1 (688) release. +--- + +# Terraform Enterprise v202303-1 (688) + +Last required release: [v202207-2 (642)](/terraform/enterprise/releases/2022/v202207-2) + +## Breaking Changes + +1. Terraform Enterprise's cookie format has been updated to increase security, and will no longer accept any cookies generated by releases prior to v202011-1. When upgrading from Terraform Enterprise v202010-1 or earlier without logging in to an interim release, any users currently logged in to the application may see a failure to load after upgrade. This failure to load can be solved by clearing the cookies for Terraform Enterprise. This potential issue will not affect users upgrading from versions newer than v202011-1 releases as long as they have been on an intermediate version for more than a month. + +## Known Issues + +1. [April 6, 2023] The `tfe-admin node-drain` command does not currently work when the `run_pipeline_mode` configuration setting is set to `agent`. See the notes under the _Highlights_ section for more details regarding this setting. This issue is fixed in the v202305-1 release. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations and End of Support + +1. The following operating systems are no longer supported: + - Debian 8, 9 + - Ubuntu 14.04, 16.04 + - Amazon Linux 2014.03, 2014.09, 2015.03, 2015.09, 2016.03, 2016.09, 2017.03, 2017.09, 2018.03 +2. The following PostgreSQL server versions are no longer supported: + - 11 +3. Terraform Build Workers are deprecated and will be removed in Terraform Enterprise v202305-1. The base image responsible for executing Terraform runs is now `hashicorp/tfc-agent`. If you are using an alternative worker image you must migrate to a new image, using `hashicorp/tfc-agent` as the base image before Terraform Enterprise v202305-1. If you are not using an alternative worker image, then you will automatically migrate to the new base image and no futher action is required. For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202303-1/replicated/administration/infrastructure/worker-to-agent-migration). +4. [Updated: August 2023] The `aws` CLI utility is no longer included in the base image. If the `aws` CLI utility is needed in your custom agent image, you may install it by following the [AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202303-1/replicated/administration/infrastructure/worker-to-agent-migration). + +## Highlights + +1. Introducing native Open Policy Agent (OPA) support, which extends the policy as code features of Terraform Enterprise to support the Rego policy language. +1. You can now use Dynamic Provider Credentials in place of static credentials for the Vault, AzureRM, AzureAD, Google Cloud Platform, and AWS providers. The [Dynamic Provider Credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) documentation has more information and prerequisites for usage. +1. This release contains a data migration for an upcoming variable sets feature. This migration will lengthen the upgrade process. The migration time will vary based on the number of variable sets attached to workspaces. It will add approximately 1 minute per 50,000 workspaces. +1. Terraform Enterprise now supports [Health assessments](/terraform/enterprise/workspaces/health). + +- [Drift detection](/terraform/enterprise/workspaces/health#drift-detection) determines whether your real-world infrastructure matches your Terraform state file. You can enable Drift detection at a workspace level or at an organization level. +- Terraform Enterprise sends [notifications](/terraform/enterprise/workspaces/settings/notifications) about health assessment results according to your workspace's settings. + +## Features + +1. A manage membership permission allows a team to invite users to the organization, and add or remove them from non-owner teams. +1. Terraform Enterprise users can now manage their GitHub App token within user settings. +1. You can use the [rotate key](/terraform/enterprise/api-docs/admin/settings#rotate-oidc-signing-key) and [trim key](/terraform/enterprise/api-docs/admin/settings#trim-oidc-signing-key) admin endpoints to control the OIDC key used to sign Workload Identity and Dynamic Provider Credential tokens. +1. Terraform Enterprise now uses Sentinel 0.20 for policy checks, bringing improvements to the JSON response and introducing named functions. + +## Improvements + +1. The plan diff UI now makes paginated requests to fetch plan log output. This prevents unconstrained memory usage in the object store service for very large plans. +1. UI workspace variables are now listed alphabetically. +1. You can now use the Terraform Enterprise API to access authorized GitHub App Installations for the current user. Requires the User API actor to generate a GitHub App user-to-server token in Terraform Enterprise UI prior to use. +1. UI application icons have been rejuvenated, migrating from a mixture of [Font Awesome](https://fontawesome.com) and [Structure](https://github.com/hashicorp/structure-icons) to the [Flight Icon library](https://helios.hashicorp.design/icons/library), which is part of the [Helios Design System](https://helios.hashicorp.design). +1. Resources can now be filtered by action types including, `Create`, `Update`, `Replace`, `Delete`, `Read`, and `Move` using the actions filter on the run page. +1. The manage-workspaces and manage-projects roles no longer require read-workspaces and read-projects permissions (respectively). Introducing a new UI that makes selecting organization-level project and workspace permissions for teams clearer, by separating Project and Workspace permissions out into their own set of interactive selectors. + +## Bug Fixes + +1. Terraform runs using the `agent` run pipeline mode will no longer fail with the error `dial unix /var/run/docker.sock: connect: permission denied` when SELinux is enforcing. +1. The agent job dequeuing logic will no longer result in a blocked agent pool and HTTP 500 errors in the tfc-agent logs. +1. Saving boolean `false` variable values no longer causes 500 errors. Null and missing values now default to empty string (""), which was the documented default. +1. Terraform plan and apply operations that are executed on internal Terraform Cloud Agents in Terraform Enterprise will now function even when the "enable agents" toggle in the site admin panel is disabled. +1. Terraform runs using the `agent` run pipeline mode now support the [`hairpin_addressing`](/terraform/enterprise/v202303-1/replicated/install/automated/automating-the-installer#hairpin_addressing) setting. When enabled, direct traffic destined for the installation's FQDN will route toward the instance's internal IP address. +1. Changing a Variable Set's scope from workspace to global will no longer result in an incorrect Variable Sets count on a workspace's "Variables" page. This was only a visual bug and has been fixed. +1. The log entry for rotating an OIDC key is now shown at the DEBUG level. Previously, it was set to INFO level. +1. The Getting Started with state guide now has the correct command `terraform apply` to copy (it had a `-` in it previously). +1. The manage-workspaces permission no longer grants read-projects. + +## Security + +1. Terraform Enterprise no longer listens on public port 23001. +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202304-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202304-1.mdx new file mode 100644 index 0000000000..18577467c1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202304-1.mdx @@ -0,0 +1,45 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202304-1 (692) release. +--- + +# Terraform Enterprise v202304-1 (692) + +**This is a required release!** + +## Known Issues + +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +1. Terraform Build Workers are deprecated and will be removed in Terraform Enterprise v202305-1. The base image responsible for executing Terraform runs is now `hashicorp/tfc-agent`. If you are using an alternative worker image you must migrate to a new image, using `hashicorp/tfc-agent` as the base image before Terraform Enterprise v202305-1. If you are not using an alternative worker image, then you will automatically migrate to the new base image and no futher action is required. For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202304-1/replicated/administration/infrastructure/worker-to-agent-migration). +2. [Updated: August 2023] The `aws` CLI utility is no longer included in the base image. If the `aws` CLI utility is needed in your custom agent image, you may install it by following the [AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202304-1/replicated/administration/infrastructure/worker-to-agent-migration). + +## Improvements + +1. The Projects List API now allows filtering by project names. You can use a `filter[names]` query parameter with one or more comma-sepearated project names and the results will be limited to projects with those exact name(s). For example: `/api/v2/organizations/my-organization/projects?filter[names]=my-project,my-other-project` +2. Application improvement now reduces network pressure during long apply operations, or until a job is marked as errored due to a killed agent process. +3. Design improvements to the user, team, and organization token UI and generation flow. +4. Highlight newly created team, user, and organization authentication tokens in the UI +5. Upgrading Sentinel to 0.21, adding support for `defined` expressions and per-policy parameter values. +6. Add ability to search an organization's teams by name and varsets by name. +7. The base font size across the application is increased to 16px in order to use the new Helios design system components at their intended size, increasing their adoption and accessibility. +8. Additional Project access roles have been added, `write` and `maintain`. For more information, refer to the [Project Team Access API](/terraform/enterprise/api-docs/project-team-access#project-team-access-levels) documentation. + +## Bug Fixes + +1. The `tfe-task-worker` container no longer fails with a permission denied error when SELinux is enforcing. +2. Background migrations will no longer wait indefinitely on database locks, and will now timeout gracefully after 2 hours and retry. +3. When a run is being cancelled, or undergoing actions that modify the state of a run, the Run Actions form will display a 'waiting' state until the run update occurs. +4. Users had reported intermittently seeing duplicate rows in the Workspace Overview "Resources" section of a workspace. This bug has been resolved and that UI updated to more consistently show the correct amount of rows, matching the number of Terraform resources managed by the workspace. +5. The application no longer needs to be refreshed after transitioning from the team settings page into user settings via the UI. +6. Sentinel will no longer assume that unknown values are boolean, fixing an issue for some Terraform plan variations. +7. Consuming private providers from other organizations no longer fails when trying to use them in a Terraform configuration. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. +2. The version of Ruby used to run the app has been updated to v3.1. +3. The Link SSO Identity to a different account page now has reCaptcha. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202305-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202305-1.mdx new file mode 100644 index 0000000000..819cbeaefe --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202305-1.mdx @@ -0,0 +1,61 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202305-1 (703) release. +--- + +# Terraform Enterprise v202305-1 (703) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +## Known Issues + +1. Some installations may experience longer page loads on pages that load a list of organizations. This issue is resolved in v202305-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +-> **Note:** The deadline for the deprecation of Terraform Build Workers has been extended to v202306-1 to ensure we support writing to environment variables. + +1. [New date] Terraform Build Workers are deprecated and will be removed in Terraform Enterprise v202306-1. The base image responsible for executing Terraform runs is now `hashicorp/tfc-agent`. If you are using an alternative worker image you must migrate to a new image, using `hashicorp/tfc-agent` as the base image before Terraform Enterprise v202306-1. If you are not using an alternative worker image, then you will automatically migrate to the new base image and no futher action is required. For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202305-1/replicated/administration/infrastructure/worker-to-agent-migration). +2. [Updated: August 2023] The `aws` CLI utility is no longer included in the base image. If the `aws` CLI utility is needed in your custom agent image, you may install it by following the [AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202305-1/replicated/administration/infrastructure/worker-to-agent-migration). + +## Features + +1. Users can now apply variable sets to specified projects. Applying a variable set to a project(s) means that the variable set is accessible to all existing and future workspaces within that project(s). + Users can apply variable sets to projects through: + +- [the variable sets settings page](/terraform/tutorials/cloud/cloud-multiple-variable-sets#create-a-credentials-variable-set) +- [the variable sets' API endpoints](/terraform/cloud-docs/api-docs/variable-sets#apply-variable-set-to-projects) +- [the TFE Terraform Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/project_variable_set) + +1. You can now specify a base64 encoded PEM format CA certificate for usage when connecting with Vault for dynamic or Vault-backed credentials via the `TFC_VAULT_ENCODED_CACERT` environment variable. +1. When creating authentication tokens for users, teams, and organizations, you can now set an expiration date and time for that token. You can no longer authenticate with tokens past their expiration date and time. +1. Dynamic Provider Credentials now support generating credentials with [Vault Dynamic Secrets Engines for AWS, Azure, and Google Cloud](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/vault-backed). +1. A TTL can now be set on a user token through the user settings of the user interface. +1. Added [automated license utilization reporting](/terraform/enterprise/v202305-1/replicated/administration/license/automated-license-utilization-reporting), which sends minimal product-license metering data to HashiCorp without requiring you to manually collect and report them. + +## Improvements + +1. Optimize workspace variable overwrite creation to speed up varset creation. Requests to create variable sets should not time out now. +1. Fixed date/timestamp on workspace resource table in Terraform Cloud's user interface. +1. Octokit now logs an error when there is a problem editing the settings of a workspace. +1. Updated the variable sets user interface to use the new Helios design system components. +1. Updated the project user interface to use the new Helios design system PowerSelect style override. +1. Improve the user interface for organization, team, and user API tokens, by updating the tokens' icon and last used text. +1. OPA tool versions are now added automatically, no longer requiring manual effort. +1. Team management at the workspace level is paginated. +1. Team management at the workspace level is searchable. +1. Workspace settings now use a fluid page layout, matching Organization settings. +1. All headings and subheadings now use the new Helios design system typography, font weight, and color to create consistency in page styling and information hierarchy for users. + +## Bug Fixes + +1. Granting a team the `manage-workspaces` or `manage-projects` organization permissions would prevent a team from accessing some resources granted by their read-only equivalents, `read-workspaces` and `read-projects`. For example, the manage permissions were not providing access to non-global variable sets, even though read permissions grant this access at the same level. +1. TFE now supports the `node-drain` command when running in `agent` run pipeline mode. +1. The `gcs_credentials` setting can now be set to `{}` to configure Terraform Enterprise to authenticate to Google Cloud Storage using the attached service account. + +# Security + +1. Updated the Nokogiri Gem, which can now [resolve multiple CVEs with libxml](https://github.com/sparklemotion/nokogiri/security/advisories/GHSA-pxvg-2qj5-37jq) +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202305-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202305-2.mdx new file mode 100644 index 0000000000..0912cefa4c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202305-2.mdx @@ -0,0 +1,63 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202305-2 (704) release. +--- + +# Terraform Enterprise v202305-2 (706) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +## Changes Since v202305-1 + +1. Some installations may experience longer page loads on pages that load a list of organizations. This issue is resolved in v202305-2. + +## Known Issues +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +-> **Note:** The deadline for the deprecation of Terraform Build Workers has been extended to v202306-1 to ensure we support writing to environment variables. + +1. [New date] Terraform Build Workers are deprecated and will be removed in Terraform Enterprise v202306-1. The base image responsible for executing Terraform runs is now `hashicorp/tfc-agent`. If you are using an alternative worker image you must migrate to a new image, using `hashicorp/tfc-agent` as the base image before Terraform Enterprise v202306-1. If you are not using an alternative worker image, then you will automatically migrate to the new base image and no futher action is required. For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202305-2/replicated/administration/infrastructure/worker-to-agent-migration). +2. [Updated: August 2023] The `aws` CLI utility is no longer included in the base image. If the `aws` CLI utility is needed in your custom agent image, you may install it by following the [AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202305-2/replicated/administration/infrastructure/worker-to-agent-migration). + +## Features + +1. Users can now apply variable sets to specified projects. Applying a variable set to a project(s) means that the variable set is accessible to all existing and future workspaces within that project(s). + Users can apply variable sets to projects through: + +- [the variable sets settings page](/terraform/tutorials/cloud/cloud-multiple-variable-sets#create-a-credentials-variable-set) +- [the variable sets' API endpoints](/terraform/cloud-docs/api-docs/variable-sets#apply-variable-set-to-projects) +- [the TFE Terraform Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/project_variable_set) + +1. You can now specify a base64 encoded PEM format CA certificate for usage when connecting with Vault for dynamic or Vault-backed credentials via the `TFC_VAULT_ENCODED_CACERT` environment variable. +1. When creating authentication tokens for users, teams, and organizations, you can now set an expiration date and time for that token. You can no longer authenticate with tokens past their expiration date and time. +1. Dynamic Provider Credentials now support generating credentials with [Vault Dynamic Secrets Engines for AWS, Azure, and Google Cloud](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/vault-backed). +1. A TTL can now be set on a user token through the user settings of the user interface. +1. Added [automated license utilization reporting](/terraform/enterprise/v202305-2/replicated/administration/license/automated-license-utilization-reporting), which sends minimal product-license metering data to HashiCorp without requiring you to manually collect and report them. + +## Improvements + +1. Optimize workspace variable overwrite creation to speed up varset creation. Requests to create variable sets should not time out now. +1. Fixed date/timestamp on workspace resource table in Terraform Cloud's user interface. +1. Octokit now logs an error when there is a problem editing the settings of a workspace. +1. Updated the variable sets user interface to use the new Helios design system components. +1. Updated the project user interface to use the new Helios design system PowerSelect style override. +1. Improve the user interface for organization, team, and user API tokens, by updating the tokens' icon and last used text. +1. OPA tool versions are now added automatically, no longer requiring manual effort. +1. Team management at the workspace level is paginated. +1. Team management at the workspace level is searchable. +1. Workspace settings now use a fluid page layout, matching Organization settings. +1. All headings and subheadings now use the new Helios design system typography, font weight, and color to create consistency in page styling and information hierarchy for users. + +## Bug Fixes + +1. Granting a team the `manage-workspaces` or `manage-projects` organization permissions would prevent a team from accessing some resources granted by their read-only equivalents, `read-workspaces` and `read-projects`. For example, the manage permissions were not providing access to non-global variable sets, even though read permissions grant this access at the same level. +1. TFE now supports the `node-drain` command when running in `agent` run pipeline mode. +1. The `gcs_credentials` setting can now be set to `{}` to configure Terraform Enterprise to authenticate to Google Cloud Storage using the attached service account. + +# Security + +1. Updated the Nokogiri Gem, which can now [resolve multiple CVEs with libxml](https://github.com/sparklemotion/nokogiri/security/advisories/GHSA-pxvg-2qj5-37jq) +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202306-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202306-1.mdx new file mode 100644 index 0000000000..4b421dc0c4 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202306-1.mdx @@ -0,0 +1,53 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202306-1 (710) release. +--- + +# Terraform Enterprise v202306-1 (713) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +## Known Issues + +1. The `RunExternalStatus` data migration now runs in the foreground for visibility. However, if there are a large number of runs this migration can take a long time to complete. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +1. In Terraform Enterprise v202308-1 the server services will be consolidated into a single container named `terraform-enterprise`. This container runs as a non-root user and contains the logs for all of the server services. Terraform runs will continue to execute in isolated, short-lived containers but will now run as a non-root user. This change is available now using the optional `consolidated_services` setting. See the [consolidated services documentation](/terraform/enterprise/v202306-1/replicated/administration/infrastructure/consolidated-services) for more information on this change. + +1. The following Docker Engine versions are deprecated. Support for them will be removed in Terraform Enterprise v202308-1. + +- Docker Engine 19.03 + +1. Terraform Build Workers are now deprecated and have been removed. The base image responsible for executing Terraform runs is now `hashicorp/tfc-agent`. If you were using an alternative worker image you must migrate to a new image, using `hashicorp/tfc-agent` as the base image. If you are not using an alternative worker image, then you will automatically migrate to the new base image and no futher action is required. For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202306-1/replicated/administration/infrastructure/worker-to-agent-migration). +1. [Updated: August 2023] The `aws` CLI utility is no longer included in the base image. If the `aws` CLI utility is needed in your custom agent image, you may install it by following the [AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). For more information, refer to the [Custom Agent Image migration guide](/terraform/enterprise/v202306-1/replicated/administration/infrastructure/worker-to-agent-migration). + +## Highlights + +1. [No-code provisioning](/terraform/enterprise/no-code-provisioning/module-design) is now available in Terraform Enterprise. No-code provisioning enables organizations to set up self-service workflows for application developers that need infrastructure but are not familiar with Terraform. +1. Docker Engine 23.0 and 24.0 are now supported. + +## Improvements + +1. You can now cancel a passed policy check to unblock runs that are stuck at the policy check step. +1. Terraform Enterprise now uses Sentinel v0.22.0 for policy checks, adding support for the `sentinel` block. +1. Prefixed the names of the ephemeral Docker containers that run Terraform plan and apply operations with "tfe-agent-". +1. The [Run Tasks Integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) payload now includes the `configuration_version_id` and `workspace_working_directory` attributes. +1. You can now access Sentinel policy check results through a new and streamlined user interface. +1. Added a new **Copy Configuration** link to copy the full configuration details of a module from its overview page. +1. The `tfe-admin retrieve-iact` command no longer contains trailing whitespace. + +## Bug Fixes + +1. Run tasks and policy sets no longer count discarded workspaces that have yet to be deleted. +1. Long workspace notification names are now properly displayed on the notifications page. +1. Long workspace run task names and descriptions are now properly displayed on the run tasks page. +1. Workspaces using the [GitHub App Integration](/terraform/enterprise/application-administration/github-app-integration) can now renew expiring refresh tokens. +1. Workspaces can no longer be assigned an agent pool that is not scoped to that workspace. Affected workspaces will revalidate their assigned agent pool on next save. +1. APIs now return project scoped variable set information for all users with the proper permissions. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202307-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202307-1.mdx new file mode 100644 index 0000000000..71ddf888ca --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202307-1.mdx @@ -0,0 +1,79 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202307-1 (722) release. +--- + +# Terraform Enterprise v202307-1 (722) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +## Known Issues + +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Breaking Changes + +1. The "Manage Policy Overrides" organization permission has been modified to remove excessive privileges. **This is a breaking change** as Policy Overriders may now require explicit additional permissions to perform other tasks. As per the [API Stability Policy](https://developer.hashicorp.com/terraform/enterprise/api-docs/stability-policy), backwards-incompatible changes may be necessary to protect your security. + + **Policy Overriders can no longer:** + _ Read cost estimate results. + _ Read run triggers. + _ Read state version outputs. + _ Read state versions. + _ Read workspace resources. + _ Read workspace variables. + + **Policy Overriders can now:** + _ List and read task stages on a run. + _ List comments on a run. \* List runs in a workspace. + +1. Cost estimation is now disabled by default for new organizations. + +## Known Issues +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). + +## Deprecations + +1. Redis v5 has reached the end of it's maintenance cycle and is no longer supported. + +2. [Updated] In Terraform Enterprise v202309-1 the server services will be consolidated into a single container named terraform-enterprise. This container runs as a non-root user and contains the logs for all of the server services. Terraform runs will continue to execute in isolated, short-lived containers but will run as a non-root user. A preview of this change is available now using the optional consolidated_services setting. See the [consolidated services documentation](https://developer.hashicorp.com/terraform/enterprise/v202307-1/replicated/administration/infrastructure/consolidated-services) for more information on this change. +3. The following Docker Engine versions are deprecated. Support for them will be removed in Terraform Enterprise v202308-1. + - Docker Engine 19.03 + - Docker Engine 20.10 +4. The following PostgreSQL server versions are no longer supported due to a [known defect](https://www.postgresql.org/about/news/postgresql-144-released-2470/): + - 14.0, 14.1, 14.2, 14.3 + +## Highlights + +1. Redis v6 and v7 are now supported. + +## Features + +1. Terraform 1.5 added the ability to import new resources by using `import` blocks in your Terraform configuration, as well as the ability to generate `resource` blocks for newly imported resources. These features are now fully supported in Terraform Enterprise. +1. [Continuous Validation](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/health#continuous-validation) is now GA for Terraform Enterprise, allowing you to regularly verify whether your workspace’s custom assertions continue to pass, validating your real-world infrastructure. + +## Improvements + +1. The variable sets web copy has been updated to fix heading capitalization and remove some redundant text. +1. The workspaces associated with a policy set can now be updated using the [policy sets PATCH endpoint](/terraform/cloud-docs/api-docs/policy-sets#update-a-policy-set). +1. Module documentation can now render GitHub emojis. +1. No-code module variables are now sorted alphabetically for consistency. +1. You can now run [on-demand Health Assessments](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/health#on-demand-assessments) for your workspace with the "Start Health Assessment" button. + +## Bug Fixes + +1. Workspaces will no longer list Run triggers where the user cannot read them. +1. Workspace email notifications will navigate the user to the relevant workspace, instead of all workspaces. +1. Per-policy parameters are now correctly configured for policy checks. +1. There were irrelevant errors related to `ddtrace` in log output. This has been resolved and these messages will no longer appear in logs. +1. Workspace resources no longer fail to be parsed when a user uploads state versions in quick succession. The workspace resources UI will now reflect the latest state version uploaded. +1. The Beta tag has been removed from No Code Provisioning flows. +1. When running with consolidated services enabled, the node-drain command now has a longer timeout and actually waits for runs to finish before terminating services. This will prevent stuck or zombied runs from appearing after restart. +1. The tfe-task-worker service will now start only after the atlas service has successfully started. This resolves an issue where, periodically, the tfe-task-worker would start and begin processing queued runs before atlas was available. This could result in a situation where the Terraform Enterprise would error during startup. +1. The task worker service now waits for the Terraform Enterprise API to be up before executing tasks. + +## Security + +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202308-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202308-1.mdx new file mode 100644 index 0000000000..8e97725a83 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202308-1.mdx @@ -0,0 +1,50 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202308-1 (725) release. +--- + +# Terraform Enterprise v202308-1 (725) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +## Known Issues +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations + +1. Terraform Enterprise no longer supports the following PostgreSQL server versions due to a [known defect](https://www.postgresql.org/about/news/postgresql-144-released-2470/): 14.0, 14.1, 14.2, and 14.3. +2. In Terraform Enterprise v202309-1 the server services will be consolidated into a single container named `terraform-enterprise`. This container runs as a non-root user and contains the logs for all server services. Terraform runs will continue to execute in isolated, short-lived containers but will run as a non-root user. A preview of this change is available now using the optional consolidated_services setting. See [consolidated services](/terraform/enterprise/v202308-1/replicated/administration/infrastructure/consolidated-services) for more information on this change. +3. When consolidated services mode is enabled in v202309-1 or higher, logs will now appear in json-lines format, and will be prepended with the name of the service that generated the log message. If you are forwarding logs, you may need to update your log forwarding configuration to accommodate the consolidated log file and the json format change. The legacy architecture will remain available until v202312-1, but will be disabled by default. If you need to revert to the legacy architecture in v202309-1 or higher, set `consolidated_services = false` in your settings.json file. For assistance please contact [support](https://support.hashicorp.com/). +4. Docker 19.03 and 20.10 have reached end of life and are no longer supported in Terraform Enterprise. + +## Features + +1. Added the ability to specify multiple dynamic provider credentials configurations per provider in a workspace. For more information, see [specifying multiple configurations](https://developer.hashicorp.com/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). +1. Adds customizable permissions for teams on a project level. Users now have the ability to set various project and workspace permissions at the project level which apply to the project itself and all workspaces contained therein. For more see our documentation on [Project Team Access](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/project-team-access#implied-custom-permission-levels). + +## Improvements + +1. Improved the load speed of the policy sets page. +1. Credentials generated in AWS when using Vault-backed dynamic credentials for AWS with the iam_user auth type are eventually consistent, meaning they can take 5-10 seconds (or more) to be valid. This was causing unexpected `InvalidClientTokenId` errors to be thrown from the AWS provider for some users. You can now specify a number of seconds to wait after requesting Vault-Backed dynamic credentials for AWS before proceeding with your Terraform run, to ensure your new credentials will be ready to use before attempting to authenticate with them. +1. The time required for Vault to issue Azure credentials is proportional to the number of Azure roles in the account. You can now specify a number of seconds to wait after requesting Vault-Backed dynamic credentials for Azure before proceeding with your Terraform run, to ensure your new credentials will be ready to use. +1. Increased the timeout on the backup and restore API endpoint, which will prevent most timeout issues when running with large data sets. +1. Terraform Enterprise has set the rate limit for the workspace runs endpoint (/api/v2/workspaces/.../runs) has been at 30/min. + +## Bug Fixes + +1. Policy Set and Run Task names no longer update page headings when editing 'name' fields. +1. Fixes a bug that prevented users from updating their organization name when there is only a letter case change. +1. Users reported seeing duplicate resources in the workspace overview for some workspaces. For those workspaces impacted, the false copies of resources will be removed. +1. Users had reported seeing errors related to `duplicate key value violates unique constraint "index_storage_deletion_requests_on_storage_record"` in their log output. This has been resolved and these messages will no longer appear. +1. Fixed an issue where users could have accidentally made private provider records with os or arch values like `${os[1]}`. Then when they attempted to delete those records, the registry request would fail, since the request URL would contain invalid characters. +1. Limited the number of repositories returned by [GitHub App VCS connections](https://developer.hashicorp.com/terraform/enterprise/application-administration/github-app-integration) to 100, to avoid timeouts that prevented the UI from loading properly when [creating a workspace/module](https://developer.hashicorp.com/terraform/enterprise/workspaces/creating#create-a-workspace). Users with more than 100 repositories will need to use the text field to specify the repository name to connect to, if it is not loaded in the list of repos. +1. Users can no longer see the option to update a variable in the workspace's variables page if they don't have permission to update variables. +1. Organization list now refreshes after modifying an organization's name. +1. Email notifications are no longer sent to suspended users or users outside the organization. + +## Security + +1. Updated the UI for required permissions for OPA policy set overrides. +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202309-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202309-1.mdx new file mode 100644 index 0000000000..776e42e6bb --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202309-1.mdx @@ -0,0 +1,48 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202309-1 (733) release. +--- + +# Terraform Enterprise v202309-1 (733) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible deployment options `terraform-enterprise` container digest: amd64/linux `sha256:20bab21966b1ff5743d3490404e6dfbd39e63b6f5ecc6848ba6b3557b540b139` + +## Known Issue +1. [Updated October 3, 2023] Azure DevOps VCS-backed workspaces may be unable to connect to the VCS, execute plans or runs, or import modules. The error in the logs shows `no matching host key type found. Their offer: ssh-rsa","component":"atlas"`. There are several workarounds available depending on the deployment option of TFE. Refer to this [knowledge base article](https://support.hashicorp.com/hc/en-us/articles/21326572948243) for more information. +1. [Updated September 29, 2023] Users reported a bug where after logging in to Terraform Enterprise, the application presents users with another "step-up" authentication login prompt when attempting to access the users settings page. A fix for this bug will be included in the `v202310-1` release. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Breaking Changes +1. This release enables the consolidated services architecture announced in [v202306-1](/terraform/enterprise/releases/2023/v202306-1). + +Application services are now consolidated into the `terraform-enterprise` container. This container runs as a non-root user and contains the logs for all application services. The `terraform-enterprise` container logs are in JSON-lines format. The 'service' key preceding the log message indicates the service that reported the log message. If using the `fluentbit` log forwarding integration, the ‘component’ metadata attribute indicates which service reported the corresponding log message. + +If you are monitoring containers or forwarding log messages to an external destination, you may need to update queries in your monitoring and log aggregation tools to reflect these changes. Terraform runs will continue to execute in isolated, short-lived containers, but will now run as a non-root user. This change can be disabled using the `consolidated_services_enabled` setting until v202401-1, when we will remove it. You can only disable this change if you are deploying with Replicated. For more details, refer to [Consolidated Services documentation](/terraform/enterprise/v202309-1/replicated/administration/infrastructure/consolidated-services). + +## Highlights +1. Terraform Enterprise now supports more flexible deployment options. You can deploy Terraform Enterprise with cloud-managed Kubernetes services (Amazon EKS, Azure AKS, and Google Cloud GKE) using helm, or with Docker Engine using Docker Compose. + * To get started with one of the new deployment options, check out the [shared requirements](/terraform/enterprise/v202309-1/flexible-deployments/install/requirements), the requirements for your desired deployment option ([docker](/terraform/enterprise/v202309-1/flexible-deployments/install/docker/requirements) or [cloud-managed Kubernetes](/terraform/enterprise/v202309-1/flexible-deployments/install/kubernetes/requirements), and the [migration guides](/terraform/enterprise/v202309-1/replicated/replicated-migration) for migrating from Replicated. + * The new lightweight, single-container architecture provides significantly faster startup times, and includes new startup checks that can help quickly diagnose configuration issues and prevent the application from starting up in a risky state. + * Flexible Deployment Options requires a new [license file](/terraform/enterprise/v202309-1/flexible-deployments/install/requirements/license) to download and install Terraform Enterprise for Docker or cloud-managed Kubernetes. All existing customers will receive the new license file by Thursday, September 21. If you do not receive your license file, please contact your HashiCorp account representative. +1. You can now apply policy sets to projects in your organization. For each run in a project's workspace, Terraform Enterprise checks the Terraform plan against the policy set. Refer to the [Policy Enforcement documentation](/terraform/cloud-docs/policy-enforcement) for details. + +## Improvements + +1. The no-code header no longer shows up in the sidebar when an organization cannot access the no-code feature. +1. All TFE installations now automatically include a copy of HashiCorp's public GPG keys. This simplifies the process of hosting an official HashiCorp Terraform provider for use in an air-gapped TFE installation. +1. Temporary run data will now be retained for 1 day instead of 1 week. This will reduce disk usage when using the mounted disk operation mode, and object storage usage when using external services or active/active mode. This change does not impact user-visible behavior. + +## Bug Fixes +1. Removed a duplicate checkbox for overriding policy sets. +1. Fixed the dropdown with search components on the Policy Set and Variable Set pages to return the correct options after a search. +1. Allow users to search for workspaces from page 2 and above. +1. Notification delivery results for emails would always display in the frontend as an error regardless of delivery outcome. The frontend status should now be updated on successful email delivery. +1. Fixes a bug where certain types of corrupt files in a module upload could cause publishing to fail without notifying the user of the failure. +1. Users should now be able to see an error message if their modules cannot be uploaded into Registry, even in some rare cases. Previously in those cases users would just keep seeing "publishing in progress" messages. + +## Security +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202310-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202310-1.mdx new file mode 100644 index 0000000000..de765fa9be --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202310-1.mdx @@ -0,0 +1,51 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202310-1 (741) release. +--- + +# Terraform Enterprise v202310-1 (741) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:b29fddcf650f384066995e7da1ddc11432851bb07c942840359e91eadf3381c2` + +## Known Issues +1. Azure DevOps VCS-backed workspaces may be unable to connect to the VCS, execute plans or runs, or import modules. The error in the logs shows `no matching host key type found. Their offer: ssh-rsa","component":"atlas"`. There are several workarounds available depending on the deployment option of TFE. Refer to this [knowledge base article](https://support.hashicorp.com/hc/en-us/articles/21326572948243) for more information. +1. [Updated October 26, 2023] For installations with `consolidated_services_enabled` set to enabled, startup checks may fail when authenticating to GCP object storage with a service account. This has been fixed in the `v202311-1` release. +1. [Updated February 26, 2024] In rare cases, no code modules created before upgrading to this release could contain errors that would cause upgrade failures. This issue is fixed in v202401-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Breaking Changes +1. [Consolidated](/terraform/enterprise/v202310-1/replicated/administration/infrastructure/consolidated-services) services mode is enabled by default as of v202309-1, but you can disable it using the `consolidated_services_enabled` setting until v202401-1, when we permanently remove it. This setting only applies to Replicated deployments. + +## Highlights +1. You can now exclude specific workspaces from global or project-scoped policy sets. Terraform Enterprise will not enforce a policy set's policies on any runs in an excluded workspace. +1. Workspace admins can now schedule automatic destroy runs to trigger the deletion of all ephemeral infrastructure managed by a workspace at some point in the future. + * You can schedule an automatic destroy in [Destruction and Deletion](/terraform/enterprise/v202310-1/workspaces/settings/deletion#automatically-destroy) under Workspace Settings. + * Workspace Event notification triggers now include auto destroy notifications. For more details, refer to the [Notification Configuration documentation](/terraform/enterprise/api-docs/notification-configurations#automatic-destroy-runs). + +## Features +1. Organizations now specify a default execution mode, which their workspaces may inherit. By default, new workspaces will inherit the organization default execution mode (and default agent pool, if applicable), but can override this default with a different execution mode. +1. Terraform Enterprise now includes an [upgrade startup check](/terraform/enterprise/v202310-1/flexible-deployments/monitoring/startup-checks) that ensures that upgrades occur in a sequential manner and do not forego required Terraform Enterprise releases. + +## Improvements +1. Terraform Enterprise can now connect to an external Vault server using TLS v1.3. +1. Added fallback mechanism for persisting Terraform state when backend errors occur during runs. + +## Bug Fixes +1. Terraform Enterprise can now connect to Redis servers using a password containing certain special characters (e.g., `+`, `<`, etc.). +1. Terraform Enterprise can now connect to database servers using a password containing certain special characters (e.g., `+`, `<`, etc.). +1. Terraform Enterprise now respects the `redis_port` configuration setting when consolidated services is enabled. +1. A user without read access to a project can no longer assign it to a policy set or see if it's already assigned. +1. Fixed premature expiration of Terraform artifacts during runs. +1. Fixed bug preventing repository publishing by ID when using ADO VCS provider. +1. Fixed validation issue for creating GitLab.com providers in regards to new key format. +1. Policy Checks will now error when attempting to queue if associated Policies or Policy Sets have been deleted, as the Policy Check is no longer valid. +1. Instruct terraform CLI to save snapshot state versions on a 1 hour interval to compensate for a terraform CLI bug in 1.5.0 ~ 1.5.7 that is saving state versions every 20 seconds in the absence of the header. +1. Users reported a bug where after logging in to Terraform Enterprise, the application presents users with another "step-up" authentication login prompt when attempting to access the user settings page. This bug has been resolved and SSO users can now access their user settings. +1. Triggering a high number of remote runs in a short time now reliably works. Previously, some jobs might be stuck in the `plan_queued` stage. + +## Security +1. Container updates address reported vulnerabilities (CVEs) in underlying packages and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202311-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202311-1.mdx new file mode 100644 index 0000000000..c1af1601ee --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202311-1.mdx @@ -0,0 +1,44 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202311-1 (742) release. +--- + +# Terraform Enterprise v202311-1 (742) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:93fad2721b712ab78723b31c8cc98d317d48d43a3acd8c0ace2425b7e372360d` + +## Known Issues +1. [Updated April 16, 2024] If you set the maximum run time on the site admin page to be longer than 24 hours, Terraform Enterprise will not trigger runs on this release version (v202311-1). Configure your maximum run time to 24 hours or less. +1. [Updated February 26, 2024] In rare cases, no code modules created before upgrading to this release could contain errors that would cause upgrade failures. This issue is fixed in v202401-2. +1. [Updated: February 26, 2024] Customers using `terraform-bundle` and that have defined a working directory may see an error in their runs that reads `Operation failed: failed packing filesystem: illegal slug error: invalid symlink`. You can work around this error using a [custom agent](/terraform/enterprise/flexible-deployments/install/custom-image) image built on `tfc-agent` v1.12. This issue is resolved in v202401-1 of Terraform Enterprise. Contact [support](https://support.hashicorp.com) for help with this issue. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Highlights +The v202311-1 release contains two significant changes that improve storage utilization: +1. You can now configure data retention policies that allow Terraform Enterprise to automatically delete old configuration versions and state versions. This prevents unbounded storage growth. +1. The overall executable plan storage footprint has been dramatically reduced by removing the provider version cache from the executable plan storage for every plan. + +## Features +1. You can now delete configuration versions and state versions to reclaim storage space. +1. State versions may be created and uploaded separately, allowing large state transmissions in terraform v1.6+ to complete without exceeding the API timeout. Previously, create and upload was a single process that could lead to timeouts when dealing with large state files. +1. Prior to Terraform v.1.6.x, the [state version API](/terraform/enterprise/api-docs/state-versions#attributes) returned archivist URLs. The API now returns TFE API URLs, which redirect to archivist URLs. To download state versions, you must follow redirects and include [authentication](/terraform/enterprise/api-docs#authentication) as described in the API overview. + +## Improvements +1. We have improved screen reader usability for the policy sets page. +1. Users that do not have access to a project receive a warning when attempting to view the project's policy set(s). +1. When creating or modifying workspaces, the version control provider section now has seperate sections for public providers and private providers. +1. We have adjusted the way we detect and report drift. These changes are targeted toward reducing noise within drift reports. + +## Bug Fixes +1. Errors parsing state (HandleParseStateJob) were incorrectly marked as successful. This has been fixed and failures will now properly return `Success == false`. +1. Workspace deletion will no longer be potentially blocked by an attached Run Task. +1. OPA policies evaluations now have more robust handling for unexpected response formats. +1. TFE installations with `consolidated_services_enabled` set to enabled now support using a service account when authenticating to GCP object storage. Previously an error would be reported on start - `{"component":"terraform-enterprise","log":"2023-10-06T04:13:52.167Z [ERROR] terraform-enterprise: check failed: name=config duration=\"34.838µs\" err=\"google storage bucket, credentials, and project must be set\""}`. + +## Security +1. Addressed HTTP/2 "Rapid Reset" ([CVE-2023-44487](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-44487), [CVE-2023-39325](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-39325)) with adoption of new Go releases and associated dependencies. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202312-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202312-1.mdx new file mode 100644 index 0000000000..ce5ca3a7d9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2023/v202312-1.mdx @@ -0,0 +1,48 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202312-1 (745) release. +--- + +# Terraform Enterprise v202312-1 (745) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:b709ccad0e3d4e4f1a8d33bea4459a70234f50e1784a11cc0cbd4056c055ecb1` + +## Known Issues +1. [Updated April 16, 2024] If you set the maximum run time on the site admin page to be longer than 24 hours, Terraform Enterprise will not trigger runs on this release version. Configure your maximum run time to 24 hours or less. +1. [Updated: February 26, 2024] Customers using `terraform-bundle` and that have defined a working directory may see an error in their runs that reads `Operation failed: failed packing filesystem: illegal slug error: invalid symlink`. You can work around this error using a [custom agent](/terraform/enterprise/v202309-1/flexible-deployments/install/custom-image) image built on `tfc-agent` v1.12. This issue is resolved in v202401-1 of Terraform Enterprise. Contact [support](https://support.hashicorp.com) for help with this issue. +1. [Updated February 26, 2024] In rare cases, no code modules created before upgrading to this release could contain errors that would cause upgrade failures. This issue is fixed in v202401-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Highlights +1. You can now designate [variable sets as a priority](/terraform/enterprise/workspaces/variables/managing-variables#priority-variable-sets), marking all variables within the set as a _priority_. Priority variables overwrite any variables with the same key set at more specific scopes in the applied workspaces. + +## Features +1. Terraform Enterprise now supports saving plans and applying them later, with the standard `terraform plan -out ` and `terraform apply ` commands. This feature requires Terraform CLI v1.6.0 or newer. You can also create saved plan runs in the API with the `save-plan` run attribute. +2. The configuration versions API now includes a new `provisional` attribute. Provisional configurations delay becoming the configuration version for their workspace upon creation. Instead, provisional configurations only become current after you apply a run using that configuration. Use this attribute when creating `save-plan` runs via the API. +1. Workload identity tokens now [work natively with the Kubernetes and Helm providers](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/kubernetes-configuration). + +## Improvements +1. We have improved screen reader usability for the variable sets page. +1. You can now configure auto-destroy runs to remove resources managed by a workspace after a period of [workspace inactivity](/terraform/enterprise/workspaces/settings/deletion#destroy-if-a-workspace-is-inactive). +1. When performing a request to the` /account/details` API with an authentication token, you can now follow the `authenticated-resource` relationship to access the underlying token holder. + +## Bug Fixes +1. Policy evaluations (i.e. native OPA support) will now be able to once again run on remote agents after a regression was introduced in v202309-1. +1. When a proxy is configured, it will be properly used during all jobs. Previously, in some situations, the proxy was not properly recognized and could lead to failures when accessing modules. +1. Custom S3 endpoints will now work properly in all configurations. +1. Project and registry module names could previously contain a newline as the final character due to an incorrect validation. +1. `tfe-task-worker` will now properly recycle connections to the host Docker socket. +1. Fixed a bug which cached administrative settings incorrectly: leading to the settings changes not applying until instance restart. +1. Deleting an organization will no longer fail when that organization has a default agent pool +1. Previously specifying multiple configurations for Vault-backed AWS or Vault-backed GCP authentication would return errors related to invalid auth types being specified in certain situations when the auth type specified was actually valid. This has been fixed and these errors should no longer be thrown when a valid auth type is specified. +1. An organization could fail to delete if an API token had been generated for that organization's owners team. Users should now be able to delete these organizations successfully. +1. The workspace count is properly outputted from the `tfe-admin license-info` now. +1. We fixed an issue with a small number of assessments triggering "create" operations that would cause assessments to fail unnecessarily. + +## Security +1. The version of Ruby used has been upgraded to 3.1.4 +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/index.mdx new file mode 100644 index 0000000000..e3d94f1fa2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/index.mdx @@ -0,0 +1,135 @@ +--- +page_title: 2024 Releases - Terraform Enterprise +description: The 2024 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2024 + +Terraform Enterprise releases from 2024 are listed in the table below. + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively in a Kubernetes environment. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | OpenShift Enabled | Linked
Terraform CLI\** | Sentinel | Tested Kubernetes Versions (EKS, AKS, GKE) | Helm Chart Version | +| ----------------- | --- |------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | ------------------ | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | *yes* | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [1.31](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.30.5](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.4](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.4) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | *yes* | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [1.31](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.30.5](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.4](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.4) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | *yes* | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [1.30](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.30](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.3](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.3) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | *yes* | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.2](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.2) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | *yes* | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.2](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.2) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | *yes* | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.2](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.2) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | *yes* | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-1-may-22-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.0) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | *yes* | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-1-may-22-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.0) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | *yes* | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.0) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | *no* | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | *no* | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | *no* | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) | +| [v202402-2](/terraform/enterprise/releases/2024/v202402-2) | *no* | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202402-1](/terraform/enterprise/releases/2024/v202402-1) | *no* | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202401-2](/terraform/enterprise/releases/2024/v202401-2) | *no* | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202401-1](/terraform/enterprise/releases/2024/v202401-1) | *no* | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202312-1](/terraform/enterprise/releases/2023/v202312-1) | *no* | [1.6.4](https://github.com/hashicorp/terraform/releases/tag/v1.6.4) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [1.24](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.24.9](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.27.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202311-1](/terraform/enterprise/releases/2023/v202311-1) | *no* | [1.6.2](https://github.com/hashicorp/terraform/releases/tag/v1.6.2) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [1.24](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.24.9](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.27.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.0) | +| [v202310-1](/terraform/enterprise/releases/2023/v202310-1) | *no* | [1.6.0](https://github.com/hashicorp/terraform/releases/tag/v1.6.0) | [0.23.0](https://docs.hashicorp.com/sentinel/changelog#0-23-0-sept-5-2023) | [1.24](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.24.9](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.27.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.0.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.0.0) | + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Docker. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Recommended Docker Compose version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202402-2](/terraform/enterprise/releases/2024/v202402-2) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202402-1](/terraform/enterprise/releases/2024/v202402-1) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202401-2](/terraform/enterprise/releases/2024/v202401-2) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202401-1](/terraform/enterprise/releases/2024/v202401-1) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [V2](https://docs.docker.com/compose/migrate/) | + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Podman. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Tested Podman version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Nomad. [Learn more about flexible deployment options](/terraform/enterprise/flexible-deployments/). + +| Version | Linked
Terraform CLI\** | Sentinel | Tested Nomad versions | Min supported version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------- | --------------------- | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | 1.5, 1.6, 1.7 | 1.5 | + + + + +Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in **March 2025**. HashiCorp will support this release until April 1, 2026. + +To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/deploy) or contact your HashiCorp account representative. + +Below is a list of the most recent Terraform Enterprise releases for the replicated deployment method. [Learn more about Replicated](/terraform/enterprise/deploy/replicated). + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI\** | Sentinel | +| ------------------------------------------------------------ | ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | 805 | [2.56.5](https://release-notes.replicated.com/release-notes/2.56.5/) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | 804 | [2.56.5](https://release-notes.replicated.com/release-notes/2.56.5/) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | 798 | [2.56.5](https://release-notes.replicated.com/release-notes/2.56.5/) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | 791 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | 789 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | 787 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | 781 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | 779 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | 776 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | 772 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | 764 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | 763 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202402-2](/terraform/enterprise/releases/2024/v202402-2) | 760 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202402-1](/terraform/enterprise/releases/2024/v202402-1) | 759 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202401-2](/terraform/enterprise/releases/2024/v202401-2) | 757 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | +| [v202401-1](/terraform/enterprise/releases/2024/v202401-1) | 751 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | + + + + + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +\** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). + +\+ This release is unavailable. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202401-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202401-1.mdx new file mode 100644 index 0000000000..e14815dad0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202401-1.mdx @@ -0,0 +1,73 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202401-1 (751) release. +--- + +# Terraform Enterprise v202401-1 (751) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:a8db9a80790b05744c19e649ba5a89a1c7a48486c956ede4e1b44927153b982a` + +## Known Issues +1. [Updated April 16, 2024] If you set the maximum run time on the site admin page to be longer than 24 hours, Terraform Enterprise will not trigger runs on this release version. Configure your maximum run time to 24 hours or less. +1. [Updated February 26, 2024] In rare cases, no code modules created before upgrading to this release could contain errors that would cause upgrade failures. This issue is fixed in v202401-2. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `consolidated_services_enabled` setting deprecation period has ended and we have removed the setting. All installations now use the single-container architecture introduced in [v202309-1](/terraform/enterprise/releases/2023/v202309-1). For more information on this change, see [consolidated services](/terraform/enterprise/v202401-1/replicated/administration/infrastructure/consolidated-services). +1. Terraform Enterprise now supports new [deployment options](/terraform/enterprise/v202401-1/flexible-deployments/) and we will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. The final Replicated release will be supported until April 1, 2026. + +To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by November 2024. For more information, refer to [the deployments overview](/terraform/enterprise/v202401-1/flexible-deployments) or contact your HashiCorp account representative. + +## Highlights +1. You can now control whether an organization's VCS status checks are aggregated. By default, new organizations aggregate VCS status checks. [Learn more about VCS status checks](/terraform/enterprise/users-teams-organizations/organizations/vcs-status-checks). +1. The private registry is introducing two features: + * A new [branch-based publishing workflow](/terraform/cloud-docs/registry/publish-modules#branch-based-publishing-considerations) alongside the tags-based publishing workflow. + * Terraform Enterprise can now [automatically run tests for modules](/terraform/enterprise/registry/test) published in your private registry using the branch-based flow. + +## Features +1. When you start a run from the Terraform Enterprise user interface and select the **Plan and Apply** run type, clicking **Additional planning options** allows you to select resource addresses to replace. +1. Site administrators can now configure site-wide [data retention policies](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) in the admin settings page. +1. Data retention policies at the organization and workspace level can now specify ["don't delete" to override parent data retention policies](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion). +1. You can now execute [policy evaluations](/terraform/enterprise/policy-enforcement) on-demand. You can also select the runtime version and workspace to evaluate against, allowing for version compatibility testing as well as workspace integration testing. +1. [Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) can now return richly formatted responses to Terraform. This enables users to use streamlined run task reviews in Terraform Enterprise, and provides meaningful context on run task evaluations without having to leave Terraform. +1. Added a new workspace setting **Auto-apply run triggers**, (API: `auto-apply-run-trigger`), which controls whether a workspace should auto-apply runs caused by changes in other workspaces. +1. Users can now pin policy tool versions (Sentinel and OPA) to execute individual policy sets. + +## Improvements +1. Removed the **VCS Branch field** on a workspace's VCS settings page for workspaces [triggering runs based on git tags](/terraform/enterprise/workspaces/settings/vcs#trigger-runs-when-a-git-tag-is-published) in order to clearly display the trigger for any vcs initiated runs. +1. Support bundles on [Docker, Kubernetes, and Podman (beta)](/terraform/enterprise/v202401-1/flexible-deployments) installations now include process information from the `terraform-enterprise` container. +1. Removed the workspace version setting summary that states versions do not upgrade automatically. When a workspace version is set to a version constraint, the version automatically resolves to the latest version which satisfies the constraint. +1. The Agent Pool edit page loads faster for agent pools available to a large number of workspaces. +1. You can now pause streaming log output to select text. +1. Sentinel Policy checks can now utilize the `resource_drift` attribute for the `tfplan/v2` import. +1. You can now expand or collapse the side navigation via a toggle button. + +## Bug Fixes +1. Runs queued for longer than 10 minutes should not longer become stuck in a pending state. +1. The state viewer component now properly checks and renders an appropriate error message for all response errors, rather than only detecting `400` responses and rendering all other response errors as inline state within the state viewer. +1. Workers running VCS repository ingestion will now drop work when it has passed the completion deadline, and can no longer be completed successfully. This mitigates issues with workers being resource constrained and unable to process all VCS ingestion due to a burst of requests. +1. Account sign up now properly creates the user's session so they are not prompted to complete step-up auth after account creation. +1. Update organization team page to have required data to correctly display 2FA badges for members. +1. Creating multiple VCS-backed workspaces will no longer create duplicate webhooks. +1. Connect Organization button will correctly navigate the user's window session to the provider's authorization page. This prevents the authorization flow being initiated in a new session. +1. The project name breadcrumb on the project settings page now links to the correct place. +1. The name input in the new project form now correctly displays error messages. +1. The Provider overview pages in the registry will now load properly. +1. Plan output will no longer show an error when nested objects contain empty attributes. +1. Fixed error "Resource diff not found" when expanding resources that are drifted but do not have changes. +1. Workspace resources' provider names are now updated after running the `terraform state replace-provider` CLI command. +1. The `tfectl` command `tfectl admin token` returns the appropriate initial admin creation URL. +1. A GitHub-backed workspace run that contains more than 300 changed files will now properly execute. + +## Security +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202401-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202401-2.mdx new file mode 100644 index 0000000000..574ad6b1c2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202401-2.mdx @@ -0,0 +1,76 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202401-2 (755) release. +--- + +# Terraform Enterprise v202401-2 (757) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:d724fa57019f0b06c10566f1d646f76c7a8b1e7ffe5ef5235a2b3a470fd05fda` + +## Changes Since v202401-1 +1. In rare cases, no code modules created before upgrading to v202401-1 could contain errors that would cause upgrade failures. This issue has been fixed, upgrades will now complete successfully even if no code modules contain errors. +1. Removed an unused Ruby gem that could cause increased memory usage in certain situations. + +## Known Issues +1. [Updated April 16, 2024] If you set the maximum run time on the site admin page to be longer than 24 hours, Terraform Enterprise will not trigger runs on this release version. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `consolidated_services_enabled` setting deprecation period has ended, and we have removed the setting. All installations now use the single-container architecture introduced in [v202309-1](/terraform/enterprise/releases/2023/v202309-1). For more information on this change, refer to [consolidated services](/terraform/enterprise/v202401-2/replicated/administration/infrastructure/consolidated-services). +1. Terraform Enterprise now supports new [deployment options](/terraform/enterprise/v202401-2/flexible-deployments/) and we will be ending support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. We will support the final Replicated release until April 1, 2026. + +To ensure you continue to receive the latest features and fixes, migrate to a new deployment option by November 2024. For more information, check out [flexible deployment options,](/terraform/enterprise/v202401-2/flexible-deployments) or contact your HashiCorp account representative. + +## Highlights +1. You can now control whether an organization's VCS status checks are aggregated. By default, new organizations aggregate VCS status checks. [Learn more about VCS status checks](/terraform/enterprise/users-teams-organizations/organizations/vcs-status-checks). +1. The private registry is introducing two features: + * A new [branch-based publishing workflow](/terraform/cloud-docs/registry/publish-modules#branch-based-publishing-considerations) alongside the tags-based publishing workflow. + * Terraform Enterprise can now [automatically run tests for modules](/terraform/enterprise/registry/test) published in your private registry using the branch-based flow. + +## Features +1. When you start a run from the Terraform Enterprise user interface and select the **Plan and Apply** run type, clicking **Additional planning options** allows you to select resource addresses to replace. +1. Site administrators can now configure site-wide [data retention policies](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) in the admin settings page. +1. Data retention policies at the organization and workspace level can now specify ["don't delete" to override parent data retention policies](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion). +1. You can now execute [policy evaluations](/terraform/enterprise/policy-enforcement) on-demand. You can also select the runtime version and workspace to evaluate against, allowing for version compatibility testing as well as workspace integration testing. +1. [Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) can now return richly formatted responses to Terraform. This enables users to use streamlined run task reviews in Terraform Enterprise, and provides meaningful context on run task evaluations without having to leave Terraform. +1. Added a new workspace setting **Auto-apply run triggers**, (API: `auto-apply-run-trigger`), which controls whether a workspace should auto-apply runs caused by changes in other workspaces. +1. Users can now pin policy tool versions (Sentinel and OPA) to execute individual policy sets. + +## Improvements +1. Removed the **VCS Branch field** on a workspace's VCS settings page for workspaces [triggering runs based on git tags](/terraform/enterprise/workspaces/settings/vcs#trigger-runs-when-a-git-tag-is-published) in order to clearly display the trigger for any vcs initiated runs. +1. Support bundles on [Docker, Kubernetes, and Podman (beta)](/terraform/enterprise/v202401-2/flexible-deployments) installations now include process information from the `terraform-enterprise` container. +1. Removed the workspace version setting summary that states versions do not upgrade automatically. When a workspace version is set to a version constraint, the version automatically resolves to the latest version which satisfies the constraint. +1. The Agent Pool edit page loads faster for agent pools available to a large number of workspaces. +1. You can now pause streaming log output to select text. +1. Sentinel Policy checks can now utilize the `resource_drift` attribute for the `tfplan/v2` import. +1. You can now expand or collapse the side navigation via a toggle button. + +## Bug Fixes +1. Runs queued for longer than 10 minutes should not longer become stuck in a pending state. +1. The state viewer component now properly checks and renders an appropriate error message for all response errors, rather than only detecting `400` responses and rendering all other response errors as inline state within the state viewer. +1. Workers running VCS repository ingestion will now drop work when it has passed the completion deadline, and can no longer be completed successfully. This mitigates issues with workers being resource constrained and unable to process all VCS ingestion due to a burst of requests. +1. Account sign up now properly creates the user's session so they are not prompted to complete step-up auth after account creation. +1. Update organization team page to have required data to correctly display 2FA badges for members. +1. Creating multiple VCS-backed workspaces will no longer create duplicate webhooks. +1. Connect Organization button will correctly navigate the user's window session to the provider's authorization page. This prevents the authorization flow being initiated in a new session. +1. The project name breadcrumb on the project settings page now links to the correct place. +1. The name input in the new project form now correctly displays error messages. +1. The Provider overview pages in the registry will now load properly. +1. Plan output will no longer show an error when nested objects contain empty attributes. +1. Fixed error "Resource diff not found" when expanding resources that are drifted but do not have changes. +1. Workspace resources' provider names are now updated after running the `terraform state replace-provider` CLI command. +1. The `tfectl` command `tfectl admin token` returns the appropriate initial admin creation URL. +1. A GitHub-backed workspace run that contains more than 300 changed files will now properly execute. + +## Security +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202402-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202402-1.mdx new file mode 100644 index 0000000000..3da3f0b8ba --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202402-1.mdx @@ -0,0 +1,52 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202402-1 (759) release. +--- + +# Terraform Enterprise v202402-1 (759) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:295dbf7b87e6fefde292ba752df1d3b4870eeca17f38d149277d1676a2d2d9ab` + +## Known Issue +1. [Updated April 16, 2024] If you set the maximum run time on the site admin page to be longer than 24 hours, Terraform Enterprise will not trigger runs on this release version. Configure your maximum run time to 24 hours or less. +1. [Updated April 15, 2024] The [backup and restore API](/terraform/enterprise/v202402-1/flexible-deployments/admin/admin-cli/backup-restore#creating-a-backup) may create incomplete backups for Terraform Enterprise installations using the mounted disk operational mode. We recommend backing up your data directories using alternative means until we fix this issue. We plan to resolve this issue in the v202404-1 release. +1. [Updated March 15, 2024] Customers that use special characters in their database password may be unable to start Terraform Enterprise. Updating the password to remove special characters will allow the application to start. The issue is being investigated, and this known issue will be updated with more information once a fix is identified. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. Terraform Enterprise now supports new [deployment options](/terraform/enterprise/v202402-1/flexible-deployments/) and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. The final Replicated release will be supported until April 1, 2026. To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by November 2024. For more information, refer to [flexible deployment options,](/terraform/enterprise/v202402-1/flexible-deployments) or contact your HashiCorp account representative. + +## Features +1. Added a new post-apply stage to the run task workflow. This stage lets you seamlessly incorporate post-provisioning tasks, which automates configuration management, compliance checks, and other post-deployment activities. +1. Terraform Enterprise now reports product usage data insights to HashiCorp (resources under management). For more information, including how to opt out, see [product usage data reporting[(/terraform/enterprise/v202402-1/flexible-deployments/admin/license#enable-product-usage-reporting. + +## Improvements +1. Added a timeout to an internal job, preventing a situation where a job could get stuck and have to be force canceled. If this time out is reached, an `ActiveRecord::QueryCanceled` exception will be raised causing the job to fail and be subject to the job's retry policy (if any). +1. Update Sentinel to 0.24.1, bringing some lower level runtime improvements. +1. The `tfrun` import will now correctly decode `null` values from the provided configuration as `null` values within policy code. +1. Improved performance of the admin users list UI. +1. Improved performance of the list workspace variables API endpoint. +1. Updated and improved the agent pool settings page UI. +1. Warnings starting with the line "Initialization autoloaded the constants" have been addressed and will no longer appear in log output +1. Flexible patch versions of Terraform can now be selected in the workspace settings, allowing you to easily select the latest patch version of a terraform minor release. + +## Bug Fixes +1. We fixed a bug where Terraform attempted to render soft-deleted state versions in the state version viewer, resulting in false errors. The state version viewer now renders an informative error message instead of attempting to render the diff for a soft-deleted state version. +1. We fixed an issue in the web app where the footer was consistently overflowing the page content. +1. We fixed an issue where Terraform was unable to list commits for branch-based registry modules from Azure DevOps. +1. Fixes a bug where changing steps in the Reauthorization of an OAuth Client flow results in the deletion of the connection. +1. Warnings starting with the line "Initialization autoloaded the constants" have been addressed and will no longer appear in log output +1. Module filters will now remain selected and results will show based on an `OR` filter. + +## Security +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202402-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202402-2.mdx new file mode 100644 index 0000000000..65b87d7fc1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202402-2.mdx @@ -0,0 +1,57 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202402-2 (760) release. +--- + +# Terraform Enterprise v202402-2 (760) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:295dbf7b87e6fefde292ba752df1d3b4870eeca17f38d149277d1676a2d2d9ab` + +## Changes Since v202402-1 +1. Databases passwords now support non-alphanumeric characters. +1. During a postgres failover, Terraform Enterprise now successfully connects to the new primary server. This fixes an issue where DNS caching was preventing the database from completely disconnecting from the old primary during a failover. + +## Known Issue +1. [Updated April 16, 2024] If you set the maximum run time on the site admin page to be longer than 24 hours, Terraform Enterprise will not trigger runs on this release version. Configure your maximum run time to 24 hours or less. +1. [Updated April 15, 2024] The [backup and restore API](/terraform/enterprise/v202402-1/flexible-deployments/admin/admin-cli/backup-restore#creating-a-backup) may create incomplete backups for Terraform Enterprise installations using the mounted disk operational mode. We recommend backing up your data directories using alternative means until we fix this issue. We have planned a resolution for the v202404-1 release. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. + +## Features +1. Added a new post-apply stage to the run task workflow. This stage lets you seamlessly incorporate post-provisioning tasks, which automates configuration management, compliance checks, and other post-deployment activities. +1. Terraform Enterprise now reports product usage data insights to HashiCorp (resources under management). For more information, including how to opt out, see [product usage data reporting[(/terraform/enterprise/v202402-1/flexible-deployments/admin/license#enable-product-usage-reporting. + +## Improvements +1. Added a timeout to an internal job, preventing a situation where a job could get stuck and have to be force canceled. If this time out is reached, an `ActiveRecord::QueryCanceled` exception will be raised causing the job to fail and be subject to the job's retry policy (if any). +1. Update Sentinel to 0.24.1, bringing some lower level runtime improvements. +1. The `tfrun` import will now correctly decode `null` values from the provided configuration as `null` values within policy code. +1. Improved performance of the admin users list UI. +1. Improved performance of the list workspace variables API endpoint. +1. Updated and improved the agent pool settings page UI. +1. Warnings starting with the line "Initialization autoloaded the constants" have been addressed and will no longer appear in log output +1. Flexible patch versions of Terraform can now be selected in the workspace settings, allowing you to easily select the latest patch version of a terraform minor release. + +## Bug Fixes +1. We fixed a bug where Terraform attempted to render soft-deleted state versions in the state version viewer, resulting in false errors. The state version viewer now renders an informative error message instead of attempting to render the diff for a soft-deleted state version. +1. We fixed an issue in the web app where the footer was consistently overflowing the page content. +1. We fixed an issue where Terraform was unable to list commits for branch-based registry modules from Azure DevOps. +1. Fixes a bug where changing steps in the Reauthorization of an OAuth Client flow results in the deletion of the connection. +1. Warnings starting with the line "Initialization autoloaded the constants" have been addressed and will no longer appear in log output +1. Module filters will now remain selected and results will show based on an `OR` filter. + +## Security +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202404-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202404-1.mdx new file mode 100644 index 0000000000..d79ad19b5a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202404-1.mdx @@ -0,0 +1,72 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202404-1 (763) release. +--- + +# Terraform Enterprise v202404-1 (763) + +~> We have pulled the v202404-1 release, making it unavailable to download due to a breaking bug. If you have already installed this release, we recommend upgrading to the v202404-2 patch release or restoring your previously installed version. + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:d4071b212178e1dfc3c18900234e2240cee873802b37107bbe394036488099a8` + +## Known Issues + +1. [Updated May 13, 2024] Replicated-based installs running in Active/Active mode are unable to properly supply a Redis configuration to the application. A fix will be available in v202405-1. +1. [Updated April 30, 2024] Customers that use S3 for backend blob storage should not upgrade to this release. The application will start, but is unable to read or write data from the blob storage. A fix is available in v202404-2. +1. [Updated April 30, 2024] If your encryption password contains certain special characters (backslash, dollar sign, grave accent, double quotation, exclamation or tilde) the application will not start successfully and will log errors decrypting vault. A fix is available in v202404-2. +1. [Updated April 30, 2024] Customers that use Terraform Enterprise with an external vault server are unable to refresh application tokens. This is fixed in v202404-2. +1. [Updated April 30, 2024] The global run tasks feature is unavailable in this version. This is fixed in v202404-2. +1. [Updated April 30, 2024] The private registry is unable to list module versions. A fix is available in v202404-2. +1. [Updated April 30, 2024] The footer shows `dev` instead of the application version. This is corrected in v202404-2. +1. [Updated June 26, 2024] After successfully running a database restore in mounted disk mode, the Terraform Enterprise container, or Replicated application, must be fully stopped and restarted in order for the application to run properly. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations + +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, please plan to migrate to a non-Replicated runtime by **November 2024**. For more information, refer to [Flexible Deployment Options](/terraform/enterprise/v202404-1/flexible-deployments/) or contact your HashiCorp account representative. +1. RedHat Enterprise will end support for RHEL v7 on June 30th, 2024. As such, Terraform Enterprise will no longer be supported on that operating system after that date. + +## Features + +1. Podman is now a supported deployment option. [Requirements](/terraform/enterprise/v202404-1/flexible-deployments/install/podman/requirements), [installation](/terraform/enterprise/v202404-1/flexible-deployments/install/podman/install) and [migration](/terraform/enterprise/v202404-1/replicated/replicated-migration#migrate-to-podman) instructions from Replicated are available. +1. You can now specify which projects can use repositories from a VCS connection. By default, Terraform Enterprise enables every workspace in an organization to access the repositories from every VCS connection. If you want to limit which projects have access to repositories from a given VCS connection, [you can change this setting](https://www.hashicorp.com/blog/terraform-cloud-improves-visibility-and-control-for-projects) to restrict connection to specific projects. +1. You can now associate a [run task](/terraform/cloud-docs/integrations/run-tasks) to all workspaces in the organization. Refer to [this blog post](https://www.hashicorp.com/blog/terraform-cloud-unveils-new-run-task-workflow-enhancements) for more details. +1. You can now create runs with debugging mode enabled from the UI and API, allowing quick access to trace level run logs. +1. You can now provide a [custom pod template](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/values.yaml#L161-L168) for worker pods with [v1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) of the helm chart. + +## Improvements + +1. Hosted agents now dequeue jobs in priority order. +1. When a user creates a new project or updates a project name whitespace is now removed from both ends of the name. The allows for a better user experience if a user accidentally adds spaces before or after. +1. Breadcrumbs for projects-related pages are now a more accurate representation of the user's location in Terraform Enterprise. +1. Bitbucket Data Center is now a supported VCS integration. +1. Workspace tasks can now be associated to more than one run stage. + +## Bug Fixes + +1. Environment variables in priority variable sets will now overwrite workspace variables with the same key. Previously, priority variable sets did not work for environment-type variables. +1. Workspaces can now be fully deleted even if they contain a state version which was rolled back. Previously, a bug caused issues with deleting workspaces under these conditions, leading to incomplete removal. +1. Searching for a Policy Set no longer is interrupted by unexpected reloads. +1. Workspaces with long names in a Kubernetes-hosted Terraform Enterprise installation can now successfully run plan or apply operations. Previously, a bug caused these operations to fail. +1. You can now use `tfe-backup-restore` to generate blob storage backups. +1. Any `tfectl` command that executes across remote nodes and takes more than 30 seconds to complete no longer fails silently. +1. All Docker container metrics now have an associated `name` label, ensuring proper identification and monitoring. +1. Terraform Enterprise no longer silently fails runs in organizations with a plan or apply timeout value exceeding 24 hours. If you had previously configured this setting to greater than 24 hours, it will be reduced to 24 hours on start. +1. The `tfectl support bundle` command now generates a complete manifest.json file. + +## Security + +1. Each service now runs under a unique user id inside the Terraform Enterprise container. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202404-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202404-2.mdx new file mode 100644 index 0000000000..d392d24b10 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202404-2.mdx @@ -0,0 +1,80 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202404-2 (764) release. +--- + +# Terraform Enterprise v202404-2 (764) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:3b564b51884573aca0dc59e7042ab6dab1cf9136284e56560805c6fef6567d69` + +## Changes Since v202404-1 +1. Terraform Enterprise properly detects S3 bucket prefixes, allowing it to read and write to the blob storage without issues. +1. External service passwords and vault encryption passwords with special characters no longer prevent Terraform Enterprise's startup. +1. External vault tokens now refresh properly. +1. You can now enable the global run tasks feature. +1. The private registry lists module versions. +1. The application footer shows the correct version of the application, `v202404-2` instead of `dev`. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Known Issues + +1. [Updated May 13, 2024] Replicated-based installs running in Active/Active mode are unable to properly supply a Redis configuration to the application. This is fixed in v202405-1. +1. [Updated May 24, 2024] Private module registry test invocations may fail when downloading the Terraform binary. This is fixed in v202405-1. +1. [Updated May 24, 2024] Terraform may fail to upload state when an older state version has no lineage value. This is fixed in v202405-1. +1. [Updated May 24, 2024] The `terraform output` command may not reflect all existing outputs. This is fixed in v202405-1. +1. [Updated May 24, 2024] The [assessment results API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/assessment-results) may not return the correct ID for the workspace relation. This is fixed in v202405-1. +1. [Updated May 24, 2024] Private modules uploaded to the Private Registry as tar files may be missing some metadata. This is fixed in v202405-1. +1. [Updated May 24, 2024] The values for the SAML configuration options `AuthnRequestsSigned` and `WantAssertionsSigned` are not being preserved in the SAML metadata. This is fixed in v202405-1. +1. [Updated May 24, 2024] Mounted Disk installations of Terraform Enterprise are failing to generate support bundles. This is fixed in v202405-1. +1. [Updated June 26, 2024] After successfully running a database restore in mounted disk mode, the Terraform Enterprise container, or Replicated application, must be fully stopped and restarted in order for the application to run properly. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. + + + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/v202404-1/flexible-deployments/) or contact your HashiCorp account representative. +1. RedHat Enterprise will end support for RHEL v7 on June 30th, 2024. As such, Terraform Enterprise will no longer be supported on that operating system after that date. + +## Features + +1. Podman is now a supported deployment option. [Requirements](/terraform/enterprise/v202404-1/flexible-deployments/install/podman/requirements), [installation](/terraform/enterprise/v202404-1/flexible-deployments/install/podman/install) and [migration](/terraform/enterprise/v202404-1/replicated/replicated-migration#migrate-to-podman) instructions from Replicated are available. +1. You can now specify which projects can use repositories from a VCS connection. By default, Terraform Enterprise enables every workspace in an organization to access the repositories from every VCS connection. If you want to limit which projects have access to repositories from a given VCS connection, [you can change this setting](https://www.hashicorp.com/blog/terraform-cloud-improves-visibility-and-control-for-projects) to restrict connection to specific projects. +1. You can now associate a [run task](/terraform/cloud-docs/integrations/run-tasks) to all workspaces in the organization. Refer to [this blog post](https://www.hashicorp.com/blog/terraform-cloud-unveils-new-run-task-workflow-enhancements) for more details. +1. You can now create runs with debugging mode enabled from the UI and API, allowing quick access to trace level run logs. +1. You can now provide a [custom pod template](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/values.yaml#L161-L168) for worker pods with [v1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) of the helm chart. + +## Improvements + +1. Hosted agents now dequeue jobs in priority order. +1. When a user creates a new project or updates a project name whitespace is now removed from both ends of the name. The allows for a better user experience if a user accidentally adds spaces before or after. +1. Breadcrumbs for projects-related pages are now a more accurate representation of the user's location in Terraform Enterprise. +1. Bitbucket Data Center is now a supported VCS integration. +1. Workspace tasks can now be associated to more than one run stage. + +## Bug Fixes + +1. Environment variables in priority variable sets will now overwrite workspace variables with the same key. Previously, priority variable sets did not work for environment-type variables. +1. Workspaces can now be fully deleted even if they contain a state version which was rolled back. Previously, a bug caused issues with deleting workspaces under these conditions, leading to incomplete removal. +1. Searching for a Policy Set no longer is interrupted by unexpected reloads. +1. Workspaces with long names in a Kubernetes-hosted Terraform Enterprise installation can now successfully run plan or apply operations. Previously, a bug caused these operations to fail. +1. You can now use `tfe-backup-restore` to generate blob storage backups. +1. Any `tfectl` command that executes across remote nodes and takes more than 30 seconds to complete no longer fails silently. +1. All Docker container metrics now have an associated `name` label, ensuring proper identification and monitoring. +1. Terraform Enterprise no longer silently fails runs in organizations with a plan or apply timeout value exceeding 24 hours. If you had previously configured this setting to greater than 24 hours, it will be reduced to 24 hours on start. +1. The `tfectl support bundle` command now generates a complete manifest.json file. + +## Security + +1. Each service now runs under a unique user id inside the Terraform Enterprise container. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202405-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202405-1.mdx new file mode 100644 index 0000000000..8827a42a61 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202405-1.mdx @@ -0,0 +1,70 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202405-1 (772) release. +--- + +# Terraform Enterprise v202405-1 (772) + +Last required release: [v202304-1 (692)](/terraform/enterprise/releases/2023/v202304-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:aea104fc8d022c06fe659aa1bcb9f13639946e6b8cdb622120fca5e61caf1397` + +## Known Issues +1. [Updated June 26, 2024] After successfully running a database restore in mounted disk mode, the Terraform Enterprise container, or Replicated application, must be fully stopped and restarted in order for the application to run properly. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To continue to receiving the latest features and fixes, migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/v202405-1/flexible-deployments/) or contact your HashiCorp account representative. + +1. RedHat Enterprise is ending support for RHEL v7 on June 30th, 2024. Following suit, Terraform Enterprise will no longer support RHEL v7 after June 30th, 2024. Replicated installations of Terraform Enterprise support RHEL 8. The Podman deployment option supports using RHEL 8 or higher. + + +## Highlights + +1. We have removed a common prefix from the keys which Redis uses for application caching. Upon upgrading, Terraform Enterprise starts with a cold cache and the size of Redis's cache data will approximately double until the old entries expire in three days. If you have an unusually large dataset in Redis and want to remove these old entries sooner, connect to Redis DB 15 and remove them manually by running `redis-cli --scan --pattern 'cache:*' | xargs redis-cli del `. +1. You can now browse projects from the dedicated [projects](/terraform/cloud-docs/workspaces/organize-workspaces-with-projects) page for better visibility and manageability. The new project overview page lets you view and search all projects you have access to. This view also provides an overview of the number of teams and workspaces associated with each project. +1. [Updated June 14, 2024] Project names can now be up to 40 characters in length. +1. Replicated installations now support Amazon Linux 2023, and RedHat Enterprise Linux 8.8. +1. The application framework underlying the Terraform Enterprise API has been upgraded from Rails 6.1 to 7.1 + + +## Features + +1. Team-enabled organizations can now delegate team management privileges to non-owners using our three new team permissions. Expanding on the existing "manage membership" permission, teams can now have the ability to "manage teams", "manage organization access", and optionally "include secret teams" at each of these permission levels. [Learn more](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions). + + +## Improvements + +1. Docker 25.0.x, 26.0.x, and 26.1.x is now supported for [Docker-based installations](/terraform/enterprise/v202405-1/flexible-deployments/install/docker/requirements) of Terraform Enterprise. +1. The team setting "Manage organization access" permission now includes a link to documentation. +1. We have paginated the workspace list on the workspace settings page where you connect run triggers. +1. The aggregated commit status page, which VCS providers link to on commits and PRs, is now more efficient when viewing runs associated with many workspaces. +1. Update the organizations list page to include pagination and the ability to create and leave organizations. +1. Updating Policy Checks to Sentinel 0.25.1, bringing with it the latest Sentinel improvements. + + +## Bug Fixes + +1. Private module registry test invocations will no longer fail when downloading the Terraform binary. +1. Terraform can now upload state even if an older state version has no lineage value. This resolves a bug that prevented Terraform from uploading state. +1. The `terraform output` command now reflect existing outputs. This resolves a bug that prevented Terraform from processing existing outputs. +1. The [assessment results API](/terraform/cloud-docs/api-docs/assessment-results) now returns the correct ID for the workspace relation. +1. Private modules uploaded as tar files to the Private Registry will now have all relevant metadata. This resolves a bug where tar files of a particular format were missing metadata. +1. The values for the SAML configuration options `AuthnRequestsSigned` and `WantAssertionsSigned` are now being set properly in the initializer. This resolves a bug where their value was not being preserved in the SAML metadata. +1. Support bundles are now available over HTTPS for Mounted Disk installations of Terraform Enterprise. This resolves a bug where the support bundle command would return an error and fail to create a support bundle. +1. Terraform Enterprise now successfully detects custom prefixes in S3 buckets when using a custom CA certificate bundle. + +## Security + +1. We have updated the internal Vault service to v1.16.2. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202406-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202406-1.mdx new file mode 100644 index 0000000000..37888daf11 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202406-1.mdx @@ -0,0 +1,65 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202406-1 (776) release. +--- + +# Terraform Enterprise v202406-1 (776) + +**This is a required release!** + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:2d6cadbc5b4956fbebe899a0ca3735108aa3fa086d380215c45298dcfc4b9c31` + +## Known Issues +1. [Updated November 21, 2024] Upgrading to v202406-1 appears to stall under the following conditions: + + - Terraform Enterprise is in `disk` mode. + - The data directory has more than 1 TB of data. + - Terraform is deployed to Replicated. + + Terraform Enterprise processes file permissions for the data during the upgrade but does not print ongoing messages to the log indicating that the operations are ongoing. + + Allow up to an hour for the upgrade, even when the following message appears in the log for an extended period of time: + + `Running as builtin tfe user, ensuring ownership of scratch directories...` + +1. [Updated September 6, 2024] This release contains a possible migration error due to orphaned team membership records referring to teams that have been deleted. If this issue affects you, the upgrade will fail. To avoid this, please refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/33051539466643-Terraform-Enterprise-version-upgrade-to-v202406-1-776-fails-with-ForeignKeyViolation) for steps to check if you have orphaned records and how to remove them before proceeding with the migration. +1. [Updated June 26, 2024] After successfully running a database restore in mounted disk mode, the Terraform Enterprise container, or Replicated application, must be fully stopped and restarted in order for the application to run properly. +1. [Updated August 14, 2024] Runs that rely on dynamic provider credentials and workload identity will fail after a certain number of signing key rotations. This problem is fixed in v202407-1, and you can avoid it by upgrading v202407-1 or above. For details on additional workarounds, including manually trimming keys, refer to [our support article](https://support.hashicorp.com/hc/en-us/articles/31715716966419-Issue-with-OIDC-Vault-key-rotation-mechanism-to-incorrectly-identify-the-newest-signing-key). +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To continue receiving the latest features, fixes, and security updates, migrate to a new deployment option by **November 2024**. For more information, refer to [Flexible Deployment Options](/terraform/enterprise/v202406-1/flexible-deployments/) or contact your HashiCorp account representative. +1. RedHat Enterprise is ending support for RHEL v7 on June 30th, 2024. Following suit, Terraform Enterprise will no longer support RHEL v7 after June 30th, 2024. Replicated installations of Terraform Enterprise support RHEL 8. The [Podman](/terraform/enterprise/flexible-deployments/install/podman/requirements) deployment option supports using RHEL 8 or higher. +1. We've removed the organizations list and navigation items from the account settings page, and instead recommend referencing your main organization page for a list of your organizations. + +## Highlights +1. This Terraform Enterprise release (v202406-1) is required, because of an upgrade of the internal PostgreSQL service from v14 to v16. This database upgrade also enables using the backup and restore API endpoints against external PostgreSQL servers running versions 15 or 16. If your upgrade fails, [restore your PostgresQL v14 database](https://support.hashicorp.com/hc/en-us/articles/29408234918035-Terraform-Enterprise-Mounted-Disk-PostgreSQL-Database-Upgrade-from-v14-to-v16). +1. Terraform Enterprise now supports a new [deployment option](/terraform/enterprise/v202406-1/flexible-deployments). Terraform Enterprise can now be deployed to HashiCorp Nomad. The feature is still in beta. To get started, refer to the [Nomad Beta requirements](/terraform/enterprise/v202406-1/flexible-deployments/install/nomad/requirements). +1. Terraform Enterprise now supports a new [deployment option](/terraform/enterprise/v202406-1/flexible-deployments). Terraform Enterprise can now be deployed to Red Hat OpenShift. The feature is still in Beta stage. To get started, read the [Kubernetes and OpenShift requirements](/terraform/enterprise/v202406-1/flexible-deployments/install/kubernetes/requirements) and instructions for [operating Terraform Enterprise on Red Hat OpenShift](/terraform/enterprise/v202406-1/flexible-deployments/install/kubernetes/openshift). + +## Features +1. You can now search for organizations by name on the main organizations page. +1. A new page has been added to allow administrators to view and cancel the current run for each workspace in an organization. For more information, refer to [Organizations](/terraform/enterprise/v202406-1/users-teams-organizations/organizations#runs). + +## Improvements +1. An organization [owner](/terraform/enterprise/v202406-1/users-teams-organizations/permissions#organization-owners) can now [leave an organization](/terraform/enterprise/v202406-1/users-teams-organizations/users#organizations) if that organization has other active owners. +1. The sentinel worker has been updated to [0.26.0](/sentinel/docs/changelog#0-26-0-may-15-2024). + +## Bug Fixes +1. The `tfe.run.limit` metric is now displayed in the JSON representation of metrics. +1. When a workspace is deleted, it will not longer appear in the variable set page. +1. Attaching a VCS provider to a project using the [attach to a project endpoint](/terraform/enterprise/v202406-1/api-docs/oauth-clients#attach-to-a-project) will no longer inadvertently remove existing projects attached to the same provider. +1. When you edit a workspace variable and wait for some time before clicking the Cancel button, the variable now reverts back to its original key and value. +1. Managing a run task with too many workspace associations could time out and display an error, preventing any updates to that run task. The number of workspace associations is now checked before loading, and will only display the workspaces if there are fewer than 50. + +## Security +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202407-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202407-1.mdx new file mode 100644 index 0000000000..b9f967dc19 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202407-1.mdx @@ -0,0 +1,59 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202407-1 (779) release. +--- + +# Terraform Enterprise v202407-1 (779) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:5d1bab736bc7fe41f7425df0f2ea5942f97091e8422e788a86a540324acb50cd` + + +## Known Issues +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12 2024 and will no longer be supported in Terraform Enterprise after that date. Please refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for a complete list of supported versions. + +## Highlights +1. You can now deploy Terraform Enterprise to OpenShift. We have updated the Helm chart with a new `openshift.enabled` value, which simplifies configuring Terraform Enterprise for OpenShift's security context requirements. For more information, refer to [Operate Terraform Enterprise on Red Hat OpenShift](/terraform/enterprise/flexible-deployments/install/kubernetes/openshift). +1. We are migrating three columns on the user table to be encrypted via Vault: `confirmation_token`, `two_factor_secret_key`, and `two_factor_recovery_secret_key`. As part of this change, a synchronous migration will be performed when updating to this release to populate the encrypted columns based on the existing plaintext columns. For customers using Terraform Enterprise's username/password authentication or the two factor authentication feature, this migration could take a little while to execute. We estimate 4ms per user to update, but the time may vary based on a variety of factors, including your hardware. All other Terraform Enterprise customers should not be impacted. After the synchronous migration has been completed, the plaintext columns will be dropped from the users table. + +## Improvements +1. We have improved the responsiveness of your organization's users page. +1. Ephemeral workspace auto-destroy runs now run within five minutes of the scheduled time. +1. The rounding threshold for run details has been increased to show a more accurate change summary. +1. The structured run output (SRO) now lists and sets planned changes according to individual elements when the collection has not changed. +1. Added the ability to pass two comma-separated Terraform versions as a constraint on workspaces. + + +## Bug Fixes + +1. OPA versions are listed correctly when creating a new OPA policy set. +1. You can now reconnect a VCS provider to an organization once the connection is revoked. +1. Terraform now directs you to the agent pools page and presents a notification when you delete an agent pool that has the **Grant access to specific workspaces** option selected with no workspaces. +1. The VCS 'File Limit Reached' message provides additional context on the VCS provider limit encountered by Terraform. +1. Dynamic credentials no longer issue invalid JWTs after the OIDC key is rotated more than nine times. +1. Terraform now waits to parse the run logs before rendering the change summary after a `plan` or `apply` operation. This prevents change summaries from flickering between no changes and the actual summary for very large changes. +1. Invalid time display will no longer appear before a health assessment has run. +1. Workspaces ending in `-` or `_` are now able to successfully execute `plan` and `apply` operations in a Kubernetes runtime environment. +1. When creating teams using an organization authentication token, the created team's visibility will now default to secret. A bug had prevented such teams from being secret, by default and by update. + +## Security + +1. The version of Ruby used has been upgraded to 3.1.5. +1. Email notifications are now sent when your session or your user token are used to create new API tokens. This provides additional security to your account. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. Updated components included `hashicorp/go-getter` (CVE-2024-6257) and `hashicorp/go-retryablehttp` (CVE-2024-6104). +1. Multiple database columns that contain user data, like two factor authentication private keys and email tokens, are now encrypted. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202408-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202408-1.mdx new file mode 100644 index 0000000000..73f5231f14 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202408-1.mdx @@ -0,0 +1,56 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202408-1 (781) release. +--- + +# Terraform Enterprise v202408-1 (781) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:c8421018a1f5cdb42fd14c9716e440ed9a1148c5f3216fc1285451eb55f3ac26` + +## Known Issues +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations + +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes in the admin organization and general settings API have been deprecated and will be removed in a future release of Terraform Enterprise. Use the new `plan-timeout` and `apply-timeout` attributes instead. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12 2024 and will no longer be supported in Terraform Enterprise after that date. Please refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for a complete list of supported versions. + +## Features +1. You can now specify a human-readable name and a URL for workspaces created using the no-code workspace API. +2. You can now specify an execution mode when creating no-code workspaces using the API. The API supports `agent` and `remote` execution modes. +3. Owners and users with the ability to "Manage Teams" are now able to enable and disable management of team tokens for members of that team. +4. You can now deploy Terraform Enterprise to Nomad. For more information, refer to the [requirements documentation](/terraform/enterprise/flexible-deployments/install/nomad/requirements) along with the [installation instructions](/terraform/enterprise/flexible-deployments/install/nomad/install). + +## Improvements +1. The `locked-reason` attribute for workspaces now appears in API response bodies and in the UI. +1. You can now set the agent job ID for Nomad-based deployments. +1. You can now specify default values for dynamic provider credentials configuration variables. This allows you to reduce duplication and define fewer variables when specifying multiple dynamic credentials configurations of the same provider type. +1. We have improved the performance of the UI for applying a variable set to a workspace. As a result, the drop-down loads faster when an organization contains a large number of variable sets. +1. Fluentbit buffer chunk size and buffer max size are now configurable through environment variables (`TFE_FLUENTBIT_BUFFERCHUNKSIZE`, `TFE_FLUENTBIT_BUFFERMAXSIZE` respectively). + +## Bug Fixes + +1. The Run tasks `Last updated` timestamp now shows the correct value. +1. Terraform Enterprise runs in a Kubernetes runtime using the default tfc-agent image will now properly inherit the CA certificate bundle content from the Terraform Enterprise Flexible Deployment Options image. +1. The `tfe-admin node-drain` and `tfectl node drain` commands now block until the node is fully drained. +1. Archivist log levels are now changed back to debug from info. +1. Resolved a bug where Nginx access logs would not be captured in support bundles or forwarded by fluentbit. + +## Security + +1. Update `rexml` to address CVE and handle parse exceptions in SAML XML configurations. +1. [All blob uploads, including configuration versions, states, and other objects, are now encrypted using AES-GCM. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-1.mdx new file mode 100644 index 0000000000..d380f8ffd5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-1.mdx @@ -0,0 +1,50 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202409-1 (787) release. +--- + +# Terraform Enterprise v202409-1 (787) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:83f2c31cfda5705f87c03ec8c3833b2deb97c1f1a90fef0ed3fc941480cd99e3` + + +## Known Issues +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations + +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes in the admin organization and general settings API have been deprecated and will be removed in a future release of Terraform Enterprise. Use the new `plan-timeout` and `apply-timeout` attributes instead. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12 2024 and will no longer be supported in Terraform Enterprise after that date. Please refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for a complete list of supported versions. + + +## Improvements + +1. A run task's associated workspaces are now paginated on the page where you edit run tasks, reducing load times for run tasks associated with many workspaces. +1. Users with VCS workspaces that contain README files may see improved response times during workspace updates. +1. New `tfectl` commands have been added to retrive the application version, `tfectl app version`, and the last completed database migrtion, `tfectl db last-applied-migration`. + + +## Bug Fixes + +1. You can now delete organizations that contain on-demand policy evaluations. +1. Previously single resource instance created with terraform `count` statement or `for-each` in HCP could not be replaced because the state-parser did not parse the index_key. Single resource instances can now be replaced. +1. Workspace Notifications have been updated to work with [workflows in Microsoft Teams](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/). + + +## Security + +1. The `ruby-saml` gem has been updated to v1.17.0 to address [CVE-2024-45409](https://github.com/advisories/GHSA-jw9c-mfg7-9rx2). Analysis of Terraform Enterprise specific exposure to this issue is currently in progress and a HashiCorp security bulletin will be published if determined appropriate. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-2.mdx new file mode 100644 index 0000000000..23c021f5f9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-2.mdx @@ -0,0 +1,53 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202409-2 (789) release. +--- + +# Terraform Enterprise v202409-2 (789) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:0be28e68ff83dcafe379aa955ce9065a3303f0fa4107e8758d9cf852fbaf98e1` + +## Changes Since v202409-1 +1. The `tfectl node drain` now properly finishes the node draining process. + + +## Known Issues +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations + +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes in the admin organization and general settings API have been deprecated and will be removed in a future release of Terraform Enterprise. Use the new `plan-timeout` and `apply-timeout` attributes instead. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12 2024 and will no longer be supported in Terraform Enterprise after that date. Please refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for a complete list of supported versions. + + +## Improvements + +1. A run task's associated workspaces are now paginated on the page where you edit run tasks, reducing load times for run tasks associated with many workspaces. +1. Users with VCS workspaces that contain README files may see improved response times during workspace updates. +1. New `tfectl` commands have been added to retrive the application version, `tfectl app version`, and the last completed database migrtion, `tfectl db last-applied-migration`. + + +## Bug Fixes + +1. You can now delete organizations that contain on-demand policy evaluations. +1. Previously single resource instance created with terraform `count` statement or `for-each` in HCP could not be replaced because the state-parser did not parse the index_key. Single resource instances can now be replaced. +1. Workspace Notifications have been updated to work with [workflows in Microsoft Teams](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/). + + +## Security + +1. The `ruby-saml` gem has been updated to v1.17.0 to address [CVE-2024-45409](https://github.com/advisories/GHSA-jw9c-mfg7-9rx2). Analysis of Terraform Enterprise specific exposure to this issue is currently in progress and a HashiCorp security bulletin will be published if determined appropriate. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-3.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-3.mdx new file mode 100644 index 0000000000..513fd91065 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202409-3.mdx @@ -0,0 +1,54 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202409-3 (791) release. +--- + +# Terraform Enterprise v202409-3 (791) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:c1297dfe64e97c32693328ec756b3023690b0b6b347a345da1778fc97c55fd32` + +## Changes Since v202409-2 +1. The `tfectl app config --format docker` compose configuration generation has been enhanced to heighten clarity around generated values and to correct theformatting of some environment variables. + +## Known Issues +1. [Updated September 30, 2024] Some deployments are experiencing memory growth issues on v202401-1 or higher, sometimes resulting in out of memory errors that require a restart to resolve. This issue is currently being investigated. It is strongly recommended that you test in a non-production environment before deploying v202401-1 or higher in production, and monitor memory for unexpected growth. This message will be updated when a fix is available in a published release. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations + +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes in the admin organization and general settings API have been deprecated and will be removed in a future release of Terraform Enterprise. Use the new `plan-timeout` and `apply-timeout` attributes instead. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12 2024 and will no longer be supported in Terraform Enterprise after that date. Please refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for a complete list of supported versions. + + +## Improvements + +1. A run task's associated workspaces are now paginated on the page where you edit run tasks, reducing load times for run tasks associated with many workspaces. +1. Users with VCS workspaces that contain README files may see improved response times during workspace updates. +1. New `tfectl` commands have been added to retrive the application version, `tfectl app version`, and the last completed database migrtion, `tfectl db last-applied-migration`. +1. The `tfectl app config --format docker` compose configuration generation has been enhanced to heighten clarity around generated values and to correct theformatting of some environment variables. + + + +## Bug Fixes + +1. You can now delete organizations that contain on-demand policy evaluations. +1. Previously single resource instance created with terraform `count` statement or `for-each` in HCP could not be replaced because the state-parser did not parse the index_key. Single resource instances can now be replaced. +1. Workspace Notifications have been updated to work with [workflows in Microsoft Teams](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/). + + +## Security + +1. The `ruby-saml` gem has been updated to v1.17.0 to address [CVE-2024-45409](https://github.com/advisories/GHSA-jw9c-mfg7-9rx2). Analysis of Terraform Enterprise specific exposure to this issue is currently in progress and a HashiCorp security bulletin will be published if determined appropriate. +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202410-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202410-1.mdx new file mode 100644 index 0000000000..be112c6c2d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202410-1.mdx @@ -0,0 +1,61 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202410-1 (798) release. +--- + +# Terraform Enterprise v202410-1 (798) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:b27c789bf92e1ee835a5fba9eba26705d71783df0eb73fbd08275ad761fbcbaa` + +# Terraform Enterprise v202410-1 + +## Deprecations + +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes in the admin organization and general settings API have been deprecated and will be removed in a future release of Terraform Enterprise. Use the new `plan-timeout` and `apply-timeout` attributes instead. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, refer to [Terraform Enterprise deployment overview](/terraform/enterprise/deploy/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12 2024 and will no longer be supported in Terraform Enterprise after that date. Refer to the requirements for [connecting a PostgreSQL ddatabase](/terraform/enterprise/deploy/configuration/storage/connect-database/postgres) for a complete list of supported versions. + +## Known Issues +1. [Updated October 28, 2024] A minor issue with Azure Kubernetes Service (AKS) workload identity authentication may prevent Terraform Enterprise from using the service consistently. To work around this issue, you must set `TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY` in your `overrides.yaml` file to a non empty string. You must also set the `TFE_OBJECT_STORAGE_AZURE_USE_MSI` setting to ` false`: +```yaml + TFE_OBJECT_STORAGE_AZURE_ACCOUNT_KEY: a25vd25faXNzdWUK # Set to any non empty string. + TFE_OBJECT_STORAGE_AZURE_USE_MSI: false +``` +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Features + +1. Extends Azure's object storage configuration with workload identity fields by providing workload identity credentials authentication for the Azure backend. +1. TFE now supports AKS workload identity authentication and authorization. + +## Improvements +1. You can now use a SHA3 certificate for SAML signing validation. +2. Teams with admin access on the default project no longer need to specify a project ID when creating a new workspace via the API. If a `project` relationship is not specified in the request, the workspace will be created in the default project as long as the caller has appropriate permission. +3. A small but constant memory leak has been discovered in the API serialization layer and fixed, which should reduce the overall memory consumption of Puma processes over time. + +## Bug Fixes + +1. Fixed a bug where some variable sets weren't visible in the `projects/:project_id/varsets` API endpoint for projects that contain no workspaces. +2. Fixed a bug where attempted eager loading of a user's teams negatively affected performance. +3. When using `tfectl app config --format docker` to generate Docker compose configurations, the output has been enhanced to heighten clarity around generated values and formatting has been corrected of some environment variables. +4. Fixed unhandled exceptions when malformed filter parameters are used in /api/v2 endpoints. +5. Workspaces API unlock action will now return a 400 status instead of 503 when the latest state version is still pending, but only for Terraform CLI 1.10+ clients. +6. Users had reported the workspace-variables page returning 404/429 responses and/or rate limiting errors when the workspace is scoped to many projects/variables. This bug has been resolved and the performance of that page has improved. +1. Services no longer fail to read the CA bundle when PostgreSQL settings are configured to either `verify-ca` or `verify-full` +1. Fixes a known issue with the execution of tfectl node drain, where the task worker would not receive a signal from the command, and the node drain would not work. + +## Security + +2. We have resolved a vulnerability in which users were able to copy their session cookie from the browser and continue to use it with the API, even after logging out, when API rate limiting was disabled in their admin settings. Terraform Enterprise always requires the cookie session to be active when making an API request authenticated with a cookie. +2. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202411-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202411-1.mdx new file mode 100644 index 0000000000..04d56b128d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202411-1.mdx @@ -0,0 +1,55 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202411-1 (804) release. +--- + +# Terraform Enterprise v202411-1 (804) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:a6bca2bcd65866a519b2bf6380b070a119bfd0176b8793ec301da7d3ba2eca79` + +# Terraform Enterprise v202411-1 + +## Known Issues +1. [Updated December 16, 2024] Starting in v202411-1, some Sentinel executions passed when they should have failed. This issue is now resolved in v202411-2. +2. [Updated November 25, 2024] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes in the admin organization and general settings API have been deprecated and will be removed in a future release of Terraform Enterprise. Use the new `plan-timeout` and `apply-timeout` attributes instead. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12, 2024 and will no longer be supported in Terraform Enterprise after that date. Please refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for a complete list of supported versions. + + +## Features +1. Support [upload part size and upload concurrency for S3 connections](/terraform/enterprise/deploy/reference/configuration#s3-compatible-storage). This is not supported on the Replicated deployment option. +1. Redis Enterprise is now supported when using two, non-clustered (single-shard) databases. More information can be found on the [Redis data page](/terraform/enterprise/deploy/configuration/storage/connect-redis#redis-enterprise). + + +## Improvements +1. Listing Policy Evaluations and Outcomes should now be faster in the Run details page. +1. Users may enable the **Automatically cancel speculative plans for outdated commits** option in the organization's settings page. +1. The introduction of the `logwatch` utility improves how Terraform Enterprise coalesces log files from individual services. Logs will not be properly captured starting when the container is up and will clearly indicate when the application has successfully started. + + +## Bug Fixes +1. A memory leak has been fixed which will dramatically reduce memory consumption over time, reducing the need for frequent restarts due to out of memory errors. +1. You can now configure Azure storage with workload identity. Previously a non-empty account key was required although not used. +1. A module's address in the Private Registry is now completely case-insensitive. Previously some differences in capitalization could return different lists of available versions. +1. Corrected a rare concurrency error that would sometimes caused Agents and Agent Jobs requests to fail. +1. When a Run terminates before the run logs are written, the UI will now display a message indicating that no run logs are available instead of 'undefined'. +1. Resolves a bug where restarting the `terraform-enterprise` process could result in some template files being incorrectly written, resulting in failures from upstream services. +1. HA Postgres failovers will no longer cause incorrect Vault token behavior in the Atlas process. +1. Terraform Enterprise will no longer crash as a result of failed Redis connectivity. + +## Security +1. Container and binary updates address reported vulnerabilities (CVEs) in underlying base images, packages, and dependencies. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202411-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202411-2.mdx new file mode 100644 index 0000000000..1d259cf555 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2024/v202411-2.mdx @@ -0,0 +1,58 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202411-2 (805) release. +--- + +# Terraform Enterprise v202411-2 (805) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:53667758b2bd71e905a4f6b194be1d4c4bffa467ec85b6b5ae945d9fcec030a7` + +# Terraform Enterprise v202411-2 + +## Changes Since v202411-1 +1. An issue has been uncovered with Sentinel execution that began in November 2024 (v202411-1) release causing runs to pass, when they should have failed. This issue is now resolved. + +## Known Issues +1. Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations +1. [Updated January 21, 2025] Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. + The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, + only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product + improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but + bug and security fixes backports will not be available after March. +1. The `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes in the admin organization and general settings API have been deprecated and will be removed in a future release of Terraform Enterprise. Use the new `plan-timeout` and `apply-timeout` attributes instead. +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026. + + To ensure you continue to receive the latest features and fixes, including security updates, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/flexible-deployments/) or contact your HashiCorp account representative. +1. The variables API endpoint, `/vars`, is deprecated and will be removed in a future release. All existing integrations with this API should transition to the [workspace variables API](/terraform/cloud-docs/api-docs/workspace-variables) `/workspaces/:workspace_id/vars`. +1. PostgreSQL v12 will reach end of life on November 12, 2024 and will no longer be supported in Terraform Enterprise after that date. Please refer to [PostgreSQL Requirements for Terraform Enterprise](/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements) for a complete list of supported versions. + + +## Features +1. Support upload part size and upload concurrency for S3 connections. This is not supported on the Replicated deployment option. +1. Redis Enterprise is now supported when using two, non-clustered (single-shard) databases. More information can be found on the [Redis data page](/terraform/enterprise/deploy/configuration/storage/connect-redis#redis-enterprise). + + +## Improvements + +1. Listing Policy Evaluations and Outcomes should now be faster in the Run details page. +1. Users may enable the **Automatically cancel speculative plans for outdated commits** option in the organization's settings page. +1. The introduction of the `logwatch` utility improves how TFE coalesces log files from individual services. + + +## Bug Fixes + +1. A memory leak has been fixed which will dramatically reduce memory consumption over time, reducing the need for frequent restarts due to out of memory errors. +1. You can now configure Azure storage with workload identity. Previously a non-empty account key was required although not used. +1. A module's address in the Private Registry is now completely case-insensitive. Previously some differences in capitalization could return different lists of available versions. +1. Corrected a rare concurrency error that would sometimes caused Agents and Agent Jobs requests to fail. +1. When a Run terminates before the run logs are written, the UI will now display a message indicating that no run logs are available instead of 'undefined'. +1. Resolves a bug where restarting the `terraform-enterprise` process could result in some template files being incorrectly written, resulting in failures from upstream services. +1. HA Postgres failovers will no longer cause incorrect Vault token behavior in the Atlas process +1. Terraform Enterprise will no longer crash as a result of failed Redis connectivity. + +## Security diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/index.mdx new file mode 100644 index 0000000000..ddf40fd1f5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/index.mdx @@ -0,0 +1,89 @@ +--- +page_title: 2025 Releases - Terraform Enterprise +description: The 2025 Terraform Enterprise releases. +--- + +# Terraform Enterprise Releases - 2025 + +Terraform Enterprise releases from 2025 are listed in the table below. + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively in a Kubernetes environment. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | OpenShift Enabled | Linked
Terraform CLI\** | Sentinel | Tested Kubernetes Versions (EKS, AKS, GKE) | Helm Chart Version | +| ----------------- | --- |------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | ------------------ | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.32](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.6.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.6.1) | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.6.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.6.0) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.5.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.5.0) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.5.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.5.0) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | *yes* | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [1.31](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.31](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.4.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.4.0) | + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Docker. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Recommended Docker Compose version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Podman. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Tested Podman version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Nomad. [Learn more about flexible deployment options](/terraform/enterprise/flexible-deployments/). + +| Version | Linked
Terraform CLI\** | Sentinel | Tested Nomad versions | Min supported version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------- | --------------------- | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | 1.7 | 1.5 | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | 1.7 | 1.5 | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | 1.7 | 1.5 | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | 1.7 | 1.5 | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | 1.7 | 1.5 | + + + + +Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in **March 2025**. HashiCorp will support this release until April 1, 2026. + +To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by **November 2024**. For more information, check out [Flexible Deployment Options](/terraform/enterprise/deploy) or contact your HashiCorp account representative. + +Below is a list of the most recent Terraform Enterprise releases for the replicated deployment method. [Learn more about Replicated](/terraform/enterprise/deploy/replicated). + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI\** | Sentinel | +| ------------------------------------------------------------ | ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | 811 | [2.56.7](https://release-notes.replicated.com/release-notes/2.56.7/) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | 810 | [2.56.6](https://release-notes.replicated.com/release-notes/2.56.6/) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | 808 | [2.56.6](https://release-notes.replicated.com/release-notes/2.56.6/) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | 806 | [2.56.6](https://release-notes.replicated.com/release-notes/2.56.6/) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | + + + + + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +\** The release package contains this version of the Terraform CLI, but you can install older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). + +\+ This release is unavailable. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202501-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202501-1.mdx new file mode 100644 index 0000000000..1e2a68bf0e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202501-1.mdx @@ -0,0 +1,50 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202501-1 (806) release. +--- + +# Terraform Enterprise v202501-1 (806) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:53a98c93d4f5e6655b439569d7fce717521e4e5655e3cf4ee107d0536fb47f0d` + +## Known Issues +1. Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Deprecations + +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. +The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, +only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product +improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but +bug and security fixes backports will not be available after March. +2. Redis 6.0 has reached end of life. Terraform Enterprise will stop supporting Redis 6.0 in April 2025. Note that this only applies +to Active-Active deployment models; Terraform Enterprise instances with external services on mounted disk deployment modes use an +internal Redis instance that is automatically updated as part of the Terraform Enterprise release process. + +## Features + +1. You can now generate dynamic provider credentials for AWS and GCP using HCP Vault Secrets-backed dynamic provider credentials. + +## Improvements + +1. If Terraform Enterprise's underlying infrastructure fails and runs appear stuck in the queued state, Terraform Enterprise identifies and updates those runs to an errored state. +2. Terraform Enterprise now includes run metadata in the streaming output logs of the `task-worker` service, such as the run ID, workload type, and organization and workspace names. This improves observability when examining logs for a specific run. +3. Terraform Enterprise now returns a specific error when it rejects streaming log uploads because of a lack of space in the cache. This change reduces network and CPU overhead for long-running jobs with large output. +4. You can now use parameters for managed policies. +5. Update Sentinel to 0.29 to stay in line with latest release. + +## Bug Fixes + +1. Resolved a bug where a no-op background migration could be stuck in an infinite loop, causing background migrations not to start. +2. Fixed an issue where certain Azure VM SKU/region combinations would cause cost estimation to hang indefinitely. +3. Fixed an issue with Azure DevOps Services & Server's new token format, causing validation errors when saving new OAuth Clients. +4. Fixes log streaming not automatically refreshing when using the console workspace UI setting. +5. Run tokens now last as long as the configured timeout for the operation they apply to, helping resolve errors where plans appear to succeed but the run fails due to token expiration. For example, if the plan timeout for an organization is 3 hours, the run token used to authenticate the plan will last longer than 3 hours. +6. Fixed the bug where invalid workspaces could cause the backfill migration to run forever. + +## Security + +1. If the IdP certificate is expired, SAML login fails with the following message: "IdP x509 certificate expired". diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202502-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202502-1.mdx new file mode 100644 index 0000000000..9a6f691979 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202502-1.mdx @@ -0,0 +1,58 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202502-1 (808) release. +--- + +# Terraform Enterprise v202502-1 (808) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:c0b547bcbc29a561936dc6b088253eeb728329da0f3e4b6db5a374b59710c24f` + +## Known Issues + +1. [Updated February 27, 2025] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. +1. [Updated March 13, 2025] The `ruby-saml` gem prior to versions 1.12.4 and 1.18.0 includes the vulnerabilites described + in [CVE-2025-25291](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-25291), + [CVE-2025-25292](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-25292), and + [CVE-2025-25293](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-25293). A HashiCorp security bulletin will be + published with additional details. This issue is fixed in v202502-2. + +## Breaking Changes + +1. Terraform Enterprise no longer supports Postgres 12. + +## Deprecations + +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. +The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, +only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product +improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but +bug and security fixes backports will not be available after March. +2. As part of improving support for HA Postgres installations, the following configuration options are deprecated and will be removed in the May 2025 release: `TFE_DATABASE_RECONNECT_ENABLED`, `TFE_DATABASE_RECONNECT_MAX_RETRIES`, `TFE_DATABASE_RECONNECT_INTERVAL`, and `TFE_DATABASE_RECONNECT_TIMEOUT`. + +## Highlights +1. This release introduces project-owned variable sets. Users with project **Write**, **Maintain**, **Admin**, or custom variable set permissions can create and manage variable sets within a project without requiring organization-level permissions. +1. You can now set auto-destroy settings at a project level, letting you [automatically destroy workspace infrastructure in a project](/terraform/enterprise/projects/manage#automatically-destroy-inactive-workspaces) after a period of inactivity. + +## Features + +1. You can add a secondary hostname in Terraform Enterprise and specify whether to use the `primary` or `secondary` hostname for OIDC integration. +1. Module authors can now [deprecate module versions](/terraform/enterprise/registry/manage-module-versions) in the private registry. Deprecating a module version in your organization’s private registry adds warnings to the module's registry page. +1. You can now select **Enable Debugging mode** when enqueuing a run for quick access to trace level Terraform logging. + +## Improvements + +1. User input is now obfuscated while typing sensitive variables and notification tokens, enhancing security, particularly during screen sharing. +1. Terraform Enterprise will now automatically attempt to unseal the internal Vault server if it unexpectedly enters a sealed state. This change has no impact on Terraform Enterprise running with an external Vault server. +1. No-code workspaces now inform users of a pending user action, such as a policy override, and direct users to the run page for further action. + +## Bug Fixes + +1. Fixes an issue with cost estimation where unexpected AWS RDS instance types could cause the cost estimate to fail. +1. Fixes a permissions bug where teams with organization permission **View all workspaces** could not view workspace outputs. +1. Fixes variable set limitation issue and significantly improves performance for the workspaces-variable page. +1. Improves queries for fetching registry modules and associations to fix performance issue in *List Modules for Organization* API. + +## Security diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202502-2.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202502-2.mdx new file mode 100644 index 0000000000..548a665de6 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202502-2.mdx @@ -0,0 +1,61 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202502-2 (810) release. +--- + +# Terraform Enterprise v202502-2 (810) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:859f963f700667237a48fad9a1588b2d5fe3c512abe89eff1384fd99c9b4225c` + +## Changes Since v202502-1 + +1. The `ruby-saml` gem has been updated to v1.18.0, which addresses [CVE-2025-25291](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-25291), + [CVE-2025-25292](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-25292), and + [CVE-2025-25293](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-25293). A HashiCorp security bulletin will be + published with additional details. + +## Known Issues + +1. [Updated February 27, 2025] Terraform Enterprise does not support usernames provided with the `REDIS_USER ` variable to authenticate with an external Redis instance. + +## Breaking Changes + +1. Terraform Enterprise no longer supports Postgres 12. + +## Deprecations + +1. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. +The final Replicated release of Terraform Enterprise will be in March 2025 (extended from November 2024). Effective December 2024, +only pre-existing workflows and capabilities will be tested for continued quality on Replicated releases. New features and product +improvements will not be validated on Replicated releases. HashiCorp Support will support this release until April 1, 2026, but +bug and security fixes backports will not be available after March. +2. As part of improving support for HA Postgres installations, the following configuration options are deprecated and will be removed in the May 2025 release: `TFE_DATABASE_RECONNECT_ENABLED`, `TFE_DATABASE_RECONNECT_MAX_RETRIES`, `TFE_DATABASE_RECONNECT_INTERVAL`, and `TFE_DATABASE_RECONNECT_TIMEOUT`. + +## Highlights +1. This release introduces project-owned variable sets. Users with project **Write**, **Maintain**, **Admin**, or custom variable set permissions can create and manage variable sets within a project without requiring organization-level permissions. +1. You can now set auto-destroy settings at a project level, letting you [automatically destroy workspace infrastructure in a project](/terraform/enterprise/projects/manage#automatically-destroy-inactive-workspaces) after a period of inactivity. + +## Features + +1. You can add a secondary hostname in Terraform Enterprise and specify whether to use the `primary` or `secondary` hostname for OIDC integration. +1. Module authors can now [deprecate module versions](/terraform/enterprise/registry/manage-module-versions) in the private registry. Deprecating a module version in your organization’s private registry adds warnings to the module's registry page. +1. You can now select **Enable Debugging mode** when enqueuing a run for quick access to trace level Terraform logging. + +## Improvements + +1. User input is now obfuscated while typing sensitive variables and notification tokens, enhancing security, particularly during screen sharing. +1. Terraform Enterprise will now automatically attempt to unseal the internal Vault server if it unexpectedly enters a sealed state. This change has no impact on Terraform Enterprise running with an external Vault server. +1. No-code workspaces now inform users of a pending user action, such as a policy override, and direct users to the run page for further action. + +## Bug Fixes + +1. Fixes an issue with cost estimation where unexpected AWS RDS instance types could cause the cost estimate to fail. +1. Fixes a permissions bug where teams with organization permission **View all workspaces** could not view workspace outputs. +1. Fixes variable set limitation issue and significantly improves performance for the workspaces-variable page. +1. Improves queries for fetching registry modules and associations to fix performance issue in *List Modules for Organization* API. + + +## Security diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202503-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202503-1.mdx new file mode 100644 index 0000000000..8cdb3d2136 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202503-1.mdx @@ -0,0 +1,40 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202503-1 (811) release. +--- + +# Terraform Enterprise v202503-1 (811) + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:65b3dee33d08a3124979ec75b02bffe44c8936014316299fd62875df0965229a` + +## Highlights + +1. You can now configure Terraform Enterprise to use Redis Sentinel. With Redis Sentinel you can achieve high availability and automatic failover. + +## Improvements + +1. Terraform Enterprise's internal tool `tfectl` no longer supports the command `db migration-status`. This command often produced confusing output regarding an internal implementation detail unrelated to proper database migrations. +1. Terraform Enterprise now creates a static number of Nginx worker processes, rather than relying on host CPU count. +1. Terraform Enterprise now displays more details when encountering errors during `tfectl` command execution. +1. The [`/variable-sets` API endpoint](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/variable-sets) returns guidance for expected variable formats instead of a generic error message when the payload for variable definitions is formatted incorrectly. +1. Team API tokens have moved to the API Tokens page in Organization Settings. You can now manage your team and organization tokens in a single place. +1. Update the Policy runtime version selector, adding more options for automatic updating. +1. Update Sentinel to 0.30, bringing with it the latest changes to the Sentinel runtime. +1. Added OPA 1.0.0 and 1.1.0, bringing with it the latest fixes and features. Both 1.0.0 and 1.1.0 introduce breaking changes, please review your policy sets to ensure a suitable version is selected. + +## Bug Fixes + +1. Resolved a bug in which Terraform Enterprise running with limited database user permissions would fail to start. +1. Resolved a bug where incorrectly encoding a secret for the internally-packaged Vault server would cause Terraform Enterprise to fail to start. +1. Fixed a bug in which large support bundles would fail to upload to S3. +1. You can now use the `REDIS_USER` variable to authenticate with your external redis dependency. Previously, you could only use the default `redis` user to authenticate. +1. The UI now supports creating variables with the same name when their categories differ. Previously, variables with the same name but different categories were blocked via the UI, even though this was possible via the API. +1. Fixes a CLI error when terraform attempts to update workspace tags during a plan operation +1. Fix a UI issue when expanding run task result outcomes + +## Security + +1. Resolved a potential ZipSlip vulnerability in the `tfe-backup-restore` service. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202504-1.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202504-1.mdx new file mode 100644 index 0000000000..f42fa666c5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/2025/v202504-1.mdx @@ -0,0 +1,33 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + Learn about the changes, known issues, deprecations, highlights, features, improvements, bug fixes, and security fixes for the v202504-1 release. +--- + +# Terraform Enterprise v202504-1 + +Last required release: [v202406-1 (776)](/terraform/enterprise/releases/2024/v202406-1) + +Flexible Deployment Options `terraform-enterprise` container digest: amd64/linux `sha256:99244574d5a2094144af82635c8ba83fd67de9762d3537e8db0ad52c118ff455` + +## Highlights + +1. You can now authenticate to the PostgreSQL server using client certificates. +2. You can now use the new `tfectl admin usage-report` cli command to manually generate product usage reports. + +## Features + +1. You can add a secondary hostname in Terraform Enterprise and specify whether to use the `primary` or `secondary` hostname for VCS and Run Task integrations. +1. You can now tag Terraform Enterprise projects, effectively tagging all of their child workspaces. +1. You can now use a key-value tagging scheme for Terraform Enterprise workspaces and projects. +1. You can now use reserved tag keys to standardize the tag keys used across your organization, or to disable the use of workspace-level overrides when administering tags at the project level. + +## Improvements + +1. The search box in the private module registry previously lost focus with each typed character, making it difficult to search for modules. This issue has been fixed, ensuring that the search box retains focus while typing. + +## Bug Fixes + +1. Terraform Enterprise now rotates the Nginx access log kept in the ephemeral filesystem. +1. Fix API error when attempting to unlock workspace after uploading state version larger than 512MB. +1. Support use of custom tool version URLs with runs. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/index.mdx new file mode 100644 index 0000000000..c2a7bbd70e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/releases/index.mdx @@ -0,0 +1,160 @@ +--- +page_title: Releases - Terraform Enterprise +description: >- + We ship a new Terraform Enterprise release each month. Find a list of recent + releases and associated release notes. +--- + +# Terraform Enterprise Releases + +~> The next release `v202505-1` is scheduled for the week of May 19, 2025. + +We release a new Terraform Enterprise version each month. The tables below list the releases for each Terraform Enterprise deployment method from the current calendar year, as well as the last required release. You can find previous releases in the sidebar. + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively in a Kubernetes environment. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | OpenShift Enabled | Linked
Terraform CLI\** | Sentinel | Tested Kubernetes Versions (EKS, AKS, GKE) | Helm Chart Version | +| ----------------- | --- |------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | ------------------ | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.32](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.6.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.6.1) | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.6.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.6.0) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.5.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.5.0) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | *yes* | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [1.32](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.32](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.5.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.5.0) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | *yes* | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [1.31](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.31](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.4.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.4.0) | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | *yes* | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [1.31](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.30.5](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.4](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.4) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | *yes* | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [1.31](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.31](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.30.5](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.4](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.4) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | *yes* | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.30](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.3](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.3) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | *yes* | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.2](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.2) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | *yes* | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.2](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.2) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | *yes* | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.2](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.2) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | *yes* | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-1-may-22-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.1) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | *yes* | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-1-may-22-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.0) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | *yes* | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.3.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.3.0) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | *no* | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | [1.29](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.29](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.29.1](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | *no* | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | *no* | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.2.0](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.2.0) | +| [v202402-2](/terraform/enterprise/releases/2024/v202402-2) | *no* | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202402-1](/terraform/enterprise/releases/2024/v202402-1) | *no* | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202401-2](/terraform/enterprise/releases/2024/v202401-2) | *no* | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | +| [v202401-1](/terraform/enterprise/releases/2024/v202401-1) | *no* | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [1.28](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [1.28](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar), [1.28.3](https://cloud.google.com/kubernetes-engine/docs/release-notes) | [1.1.1](https://github.com/hashicorp/terraform-enterprise-helm/releases/tag/v1.1.1) | + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Docker. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Recommended Docker Compose version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202402-2](/terraform/enterprise/releases/2024/v202402-2) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202402-1](/terraform/enterprise/releases/2024/v202402-1) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202401-2](/terraform/enterprise/releases/2024/v202401-2) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [V2](https://docs.docker.com/compose/migrate/) | +| [v202401-1](/terraform/enterprise/releases/2024/v202401-1) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | [V2](https://docs.docker.com/compose/migrate/) | + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Podman. [Learn more about flexible deployment options](/terraform/enterprise/deploy/). + +| Version | Linked
Terraform CLI\** | Sentinel | Tested Podman version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [v5](https://github.com/containers/podman/releases/tag/v5.0.0) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | [v4.3.0](https://podman.io/release/2022/10/22/podman-release-v4.3.0) | + + + + + +Below is a list of the most recent Terraform Enterprise Releases that can deploy Terraform Enterprise natively using Nomad. [Learn more about flexible deployment options](/terraform/enterprise/flexible-deployments/). + +| Version | Linked
Terraform CLI\** | Sentinel | Tested Nomad versions | Min supported version | +| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------- | --------------------- | +| [v202504-1](/terraform/enterprise/releases/2025/v202504-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | 1.7 | 1.5 | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | 1.7 | 1.5 | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | 1.7 | 1.5 | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | 1.7 | 1.5 | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | 1.7 | 1.5 | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | 1.5, 1.6, 1.7 | 1.5 | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | 1.5, 1.6, 1.7 | 1.5 | + + + + + +Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler +option. The final Replicated release of Terraform Enterprise was published in **March 2025**. HashiCorp will support +this release until April 1, 2026. + +To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by **November 2024**. For more information, refer to [Terraform Enterprise deployment overview](/terraform/enterprise/deploy) or contact your HashiCorp account representative. + +Below is a list of the most recent Terraform Enterprise releases for the replicated deployment method. [Learn more about Replicated](/terraform/enterprise/deploy/replicated). + +| Version | Release Sequence | Recommended
Replicated CLI | Linked
Terraform CLI\** | Sentinel | +| ------------------------------------------------------------ | ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [v202503-1](/terraform/enterprise/releases/2025/v202503-1) | 811 | [2.56.7](https://release-notes.replicated.com/release-notes/2.56.7/) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.30.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-30-0-february-17-2025) | +| [v202502-2](/terraform/enterprise/releases/2025/v202502-2) | 810 | [2.56.6](https://release-notes.replicated.com/release-notes/2.56.6/) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | +| [v202502-1](/terraform/enterprise/releases/2025/v202502-1) | 808 | [2.56.6](https://release-notes.replicated.com/release-notes/2.56.6/) | [1.10.5](https://github.com/hashicorp/terraform/releases/tag/v1.10.5) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | +| [v202501-1](/terraform/enterprise/releases/2025/v202501-1) | 806 | [2.56.6](https://release-notes.replicated.com/release-notes/2.56.6/) | [1.10.1](https://github.com/hashicorp/terraform/releases/tag/v1.10.1) | [0.29.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-29-0-november-26-2024) | +| [v202411-2](/terraform/enterprise/releases/2024/v202411-2) | 805 | [2.56.5](https://release-notes.replicated.com/release-notes/2.56.5/) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | +| [v202411-1](/terraform/enterprise/releases/2024/v202411-1) | 804 | [2.56.5](https://release-notes.replicated.com/release-notes/2.56.5/) | [1.9.8](https://github.com/hashicorp/terraform/releases/tag/v1.9.8) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | +| [v202410-1](/terraform/enterprise/releases/2024/v202410-1) | 798 | [2.56.5](https://release-notes.replicated.com/release-notes/2.56.5/) | [1.9.6](https://github.com/hashicorp/terraform/releases/tag/v1.9.6) | [0.28.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-28-0-september-26-2024) | +| [v202409-3](/terraform/enterprise/releases/2024/v202409-3) | 791 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | +| [v202409-2](/terraform/enterprise/releases/2024/v202409-2) | 789 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | +| [v202409-1](/terraform/enterprise/releases/2024/v202409-1) | 787 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.5](https://github.com/hashicorp/terraform/releases/tag/v1.9.5) | [0.27.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-27-0-august-7-2024) | +| [v202408-1](/terraform/enterprise/releases/2024/v202408-1) | 781 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.9.2](https://github.com/hashicorp/terraform/releases/tag/v1.9.2) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | +| [v202407-1](/terraform/enterprise/releases/2024/v202407-1) | 779 | [2.56.4](https://release-notes.replicated.com/release-notes/2.56.4/) | [1.8.5](https://github.com/hashicorp/terraform/releases/tag/v1.8.5) | [0.26.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-22-2024) | +| [v202406-1](/terraform/enterprise/releases/2024/v202406-1)* | 776 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.3](https://github.com/hashicorp/terraform/releases/tag/v1.8.3) | [0.26.0](https://developer.hashicorp.com/sentinel/docs/changelog#0-26-0-may-15-2024) | +| [v202405-1](/terraform/enterprise/releases/2024/v202405-1) | 772 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.2](https://github.com/hashicorp/terraform/releases/tag/v1.8.2) | [0.25.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-25-1-apr-18-2024) | +| [v202404-2](/terraform/enterprise/releases/2024/v202404-2) | 764 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202404-1](/terraform/enterprise/releases/2024/v202404-1)+ | 763 | [2.56.3](https://release-notes.replicated.com/release-notes/2.56.3/) | [1.8.1](https://github.com/hashicorp/terraform/releases/tag/v1.8.1) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202402-2](/terraform/enterprise/releases/2024/v202402-2) | 760 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202402-1](/terraform/enterprise/releases/2024/v202402-1) | 759 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.4](https://github.com/hashicorp/terraform/releases/tag/v1.7.4) | [0.24.2](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-2-jan-31-2024) | +| [v202401-2](/terraform/enterprise/releases/2024/v202401-2) | 757 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | +| [v202401-1](/terraform/enterprise/releases/2024/v202401-1) | 751 | [2.56.2](https://release-notes.replicated.com/release-notes/2.56.2/) | [1.7.1](https://github.com/hashicorp/terraform/releases/tag/v1.7.1) | [0.23.1](https://developer.hashicorp.com/sentinel/docs/changelog#0-24-1-jan-19-2024) | + + + + +\* Denotes a required release. All online upgrades will automatically install this version, but airgap customers must upgrade to this version before proceeding to later releases. + +\** The release package contains a link to this version of the Terraform CLI. A linked version still requires Terraform Enterprise to download the Terraform CLI on each run. You can link older and newer versions of the Terraform CLI as needed via the Admin [UI](/terraform/enterprise/application-administration/resources#managing-terraform-versions) or [API](/terraform/enterprise/api-docs/admin/terraform-versions). + +\+ This release is unavailable. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/api.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/api.mdx new file mode 100644 index 0000000000..eaf923fce2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/api.mdx @@ -0,0 +1,197 @@ +--- +page_title: The API-driven run workflow in Terraform Enterprise +description: >- + Use Terraform Enterprise's API-driven run workflow to enable external tools to + upload Terraform configurations and trigger new runs. +source: terraform-docs-common +--- + +# The API-driven run workflow + +HCP Terraform has three workflows for managing Terraform runs. + +- The [UI/VCS-driven run workflow](/terraform/enterprise/run/ui), which is the primary mode of operation. +- The API-driven run workflow described below, which is more flexible but requires you to create some tooling. +- The [CLI-driven run workflow](/terraform/enterprise/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +## Summary + +In the API-driven workflow, workspaces are not directly associated with a VCS repo, and runs are not driven by webhooks on your VCS provider. + +Instead, one of your organization's other tools is in charge of deciding when configuration has changed and a run should occur. Usually this is something like a CI system, or something else capable of monitoring changes to your Terraform code and performing actions in response. + +Once your other tooling has decided a run should occur, it must make a series of calls to HCP Terraform's `runs` and `configuration-versions` APIs to upload configuration files and perform a run with them. For the exact series of API calls, see the [pushing a new configuration version](#pushing-a-new-configuration-version) section. + +The most significant difference in this workflow is that HCP Terraform _does not_ fetch configuration files from version control. Instead, your own tooling must upload the configurations as a `.tar.gz` file. This allows you to work with configurations from unsupported version control systems, automatically generate Terraform configurations from some other source of data, or build a variety of other integrations. + +~> **Important:** The script below is provided to illustrate the run process, and is not intended for production use. If you want to drive HCP Terraform runs from the command line, please see the [CLI-driven run workflow](/terraform/enterprise/run/cli). + +## Pushing a New Configuration Version + +Pushing a new configuration to an existing workspace is a multi-step process. This section walks through each step in detail, using an example bash script to illustrate. + +You need queue plans permission to create new configuration versions for the workspace. Refer to the [permissions](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) documentation for more details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### 1. Define Variables + +To perform an upload, a few user parameters must be set: + +- **path_to_content_directory** is the folder with the terraform configuration. There must be at least one `.tf` file in the root of this path. +- **organization** is the organization name (not ID) for your HCP Terraform organization. +- **workspace** is the workspace name (not ID) in the HCP Terraform organization. +- **$TOKEN** is the API Token used for [authenticating with the HCP Terraform API](/terraform/enterprise/api-docs#authentication). + +This script extracts the `path_to_content_directory`, `organization`, and `workspace` from command line arguments, and expects the `$TOKEN` as an environment variable. + +```bash +#!/bin/bash + +if [ -z "$1" ] || [ -z "$2" ]; then + echo "Usage: $0 /" + exit 0 +fi + +CONTENT_DIRECTORY="$1" +ORG_NAME="$(cut -d'/' -f1 <<<"$2")" +WORKSPACE_NAME="$(cut -d'/' -f2 <<<"$2")" +``` + +### 2. Create the File for Upload + +The [configuration version API](/terraform/enterprise/api-docs/configuration-versions) requires a `tar.gz` file to use the configuration version for a run, so you must package the directory containing the Terraform configuration into a `tar.gz` file. + +~> **Important:** The configuration directory must be the root of the tar file, with no intermediate directories. In other words, when the tar file is extracted the result must be paths like `./main.tf` rather than `./terraform-appserver/main.tf`. + +```bash +UPLOAD_FILE_NAME="./content-$(date +%s).tar.gz" +tar -zcvf "$UPLOAD_FILE_NAME" -C "$CONTENT_DIRECTORY" . +``` + +### 3. Look Up the Workspace ID + +The first step identified the organization name and the workspace name; however, the [configuration version API](/terraform/enterprise/api-docs/configuration-versions) expects the workspace ID. As such, the ID has to be looked up. If the workspace ID is already known, this step can be skipped. This step uses the [`jq` tool](https://stedolan.github.io/jq/) to parse the JSON output and extract the ID value into the `WORKSPACE_ID` variable. + +```bash +WORKSPACE_ID=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/$ORG_NAME/workspaces/$WORKSPACE_NAME \ + | jq -r '.data.id')) +``` + +### 4. Create a New Configuration Version + +Before uploading the configuration files, you must create a `configuration-version` to associate uploaded content with the workspace. This API call performs two tasks: it creates the new configuration version and it extracts the upload URL to be used in the next step. + +```bash +echo '{"data":{"type":"configuration-versions"}}' > ./create_config_version.json + +UPLOAD_URL=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @create_config_version.json \ + https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/configuration-versions \ + | jq -r '.data.attributes."upload-url"')) +``` + +### 5. Upload the Configuration Content File + +Next, upload the configuration version `tar.gz` file to the upload URL extracted from the previous step. If a file is not uploaded, the configuration version will not be usable, since it will have no Terraform configuration files. + +HCP Terraform automatically creates a new run with a plan once the new file is uploaded. If the workspace is configured to auto-apply, it will also apply if the plan succeeds; otherwise, an apply can be triggered via the [Run Apply API](/terraform/enterprise/api-docs/run#apply). If the API token used for the upload lacks permission to apply runs for the workspace, the run can't be auto-applied. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +```bash +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @"$UPLOAD_FILE_NAME" \ + $UPLOAD_URL +``` + +### 6. Delete Temporary Files + +In the previous steps a few files were created; they are no longer needed, so they should be deleted. + +```bash +rm "$UPLOAD_FILE_NAME" +rm ./create_config_version.json +``` + +### Complete Script + +Combine all of the code blocks into a single file, `./terraform-enterprise-push.sh` and give execution permission to create a combined bash script to perform all of the operations. + +```shell +chmod +x ./terraform-enterprise-push.sh +./terraform-enterprise-push.sh ./content my-organization/my-workspace +``` + +**Note**: This script does not have error handling, so for a more robust script consider adding error checking. + +**`./terraform-enterprise-push.sh`:** + +```bash +#!/bin/bash + +# Complete script for API-driven runs. + +# 1. Define Variables + +if [ -z "$1" ] || [ -z "$2" ]; then + echo "Usage: $0 /" + exit 0 +fi + +CONTENT_DIRECTORY="$1" +ORG_NAME="$(cut -d'/' -f1 <<<"$2")" +WORKSPACE_NAME="$(cut -d'/' -f2 <<<"$2")" + +# 2. Create the File for Upload + +UPLOAD_FILE_NAME="./content-$(date +%s).tar.gz" +tar -zcvf "$UPLOAD_FILE_NAME" -C "$CONTENT_DIRECTORY" . + +# 3. Look Up the Workspace ID + +WORKSPACE_ID=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/$ORG_NAME/workspaces/$WORKSPACE_NAME \ + | jq -r '.data.id')) + +# 4. Create a New Configuration Version + +echo '{"data":{"type":"configuration-versions"}}' > ./create_config_version.json + +UPLOAD_URL=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @create_config_version.json \ + https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/configuration-versions \ + | jq -r '.data.attributes."upload-url"')) + +# 5. Upload the Configuration Content File + +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @"$UPLOAD_FILE_NAME" \ + $UPLOAD_URL + +# 6. Delete Temporary Files + +rm "$UPLOAD_FILE_NAME" +rm ./create_config_version.json +``` + +## Advanced Use Cases + +For advanced use cases refer to the [Terraform Enterprise Automation Script](https://github.com/hashicorp/terraform-guides/tree/master/operations/automation-script) repository for automating interactions with HCP Terraform, including the creation of a workspace, uploading code, setting variables, and triggering the `plan` and `apply` operations. + +In addition to uploading configurations and starting runs, you can use HCP Terraform's APIs to create and modify workspaces, edit variable values, and more. See the [API documentation](/terraform/enterprise/api-docs) for more details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/cli.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/cli.mdx new file mode 100644 index 0000000000..87c74d475f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/cli.mdx @@ -0,0 +1,299 @@ +--- +page_title: The CLI-driven remote run workflow for Terraform Enterprise +description: >- + Configure the Terraform CLI to trigger remote runs in Terraform Enterprise + from your terminal. +source: terraform-docs-common +--- + +[private]: /terraform/enterprise/registry + +[speculative plan]: /terraform/enterprise/run/remote-operations#speculative-plans + +[tfe-provider]: https://registry.terraform.io/providers/hashicorp/tfe/latest/docs + +# The CLI-driven remote run workflow + +> **Hands-on:** Try the [Log in to HCP Terraform from the CLI](/terraform/tutorials/0-13/cloud-login) tutorial. + +HCP Terraform has three workflows for managing Terraform runs. + +- The [UI/VCS-driven run workflow](/terraform/enterprise/run/ui), which is the primary mode of operation. +- The [API-driven run workflow](/terraform/enterprise/run/api), which is more flexible but requires you to create some tooling. +- The CLI-driven run workflow described below, which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +## Summary + +The [CLI integration](/terraform/cli/cloud) brings HCP Terraform's collaboration features into the familiar Terraform CLI workflow. It offers the best of both worlds to developers who are already comfortable with using the Terraform CLI, and it can work with existing CI/CD pipelines. + +You can start runs with the standard `terraform plan` and `terraform apply` commands and then watch the progress of the run from your terminal. These runs execute remotely in HCP Terraform, use variables from the appropriate workspace, enforce any applicable [Sentinel or OPA policies](/terraform/enterprise/policy-enforcement), and can access HCP Terraform's [private registry][private] and remote state inputs. + +HCP Terraform offers a few types of CLI-driven runs, to support different stages of your workflow: + +- `terraform plan` starts a [speculative plan][] in an HCP Terraform workspace, using configuration files from a local directory. You can quickly check the results of edits (including compliance with Sentinel policies) without needing to copy sensitive variables to your local machine. + + Speculative plans work with all workspaces, and can co-exist with the [VCS-driven workflow](/terraform/enterprise/run/ui). + +- `terraform apply` starts a standard plan and apply in an HCP Terraform workspace, using configuration files from a local directory. + + Remote `terraform apply` is for workspaces without a linked VCS repository. It replaces the VCS-driven workflow with a more traditional CLI workflow. + +- `terraform plan -out ` and `terraform apply ` perform a two-part [saved plan run](/terraform/enterprise/run/modes-and-options/#saved-plans) in an HCP Terraform workspace, using configuration files from a local directory. The first command performs and saves the plan, and the second command applies it. You can use `terraform show ` to inspect a saved plan. + + Like remote `terraform apply`, remote saved plans are for workspaces without a linked VCS repository. + + Saved plans require at least Terraform CLI v1.6.0. + +To supplement these remote operations, you can also use the optional [Terraform Enterprise Provider][tfe-provider], which interacts with the HCP Terraform-supported resources. This provider is useful for editing variables and workspace settings through the Terraform CLI. + +## Configuration + +To enable the CLI-driven workflow, you must: + +1. Create an account or sign in to [HCP Terraform](https://app.terraform.io/). + +2. Run `terraform login` to authenticate with HCP Terraform. Alternatively, you can manually configure credentials in the CLI config file or through environment variables. Refer to [CLI Configuration](/terraform/cli/config/config-file#environment-variable-credentials) for details. + +3. Add the `cloud` block to your Terraform configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for [non-interactive workflows](#non-interactive-workflows). Refer to [Using HCP Terraform](/terraform/cli/cloud) for configuration details. + + The following example shows how to map CLI workspaces to HCP Terraform workspaces with a specific tag. + + terraform { + cloud { + organization = "my-org" + workspaces { + tags = ["networking"] + } + } + } + + -> **Note:** The `cloud` block is available in Terraform v1.1 and later. Previous versions can use the [`remote` backend](/terraform/language/settings/backends/remote) to configure the CLI workflow and migrate state. + +4. Run `terraform init`. + + $ terraform init + + Initializing HCP Terraform... + + Initializing provider plugins... + - Reusing previous version of hashicorp/random from the dependency lock file + - Using previously-installed hashicorp/random v3.0.1 + + HCP Terraform has been successfully initialized! + + You may now begin working with HCP Terraform. Try running "terraform plan" + to see any changes that are required for your infrastructure. + + If you ever set or change modules or Terraform Settings, + run "terraform init" again to reinitialize your working directory. + +### Implicit Workspace Creation + +If you configure the `cloud` block to use a workspace that doesn't yet exist in your organization, HCP Terraform will create a new workspace with that name when you run `terraform init`. The output of `terraform init` will inform you when this happens. + +Automatically created workspaces might not be immediately ready to use, so use HCP Terraform's UI to check a workspace's settings and data before performing any runs. In particular, note that: + +- No Terraform variables or environment variables are created by default, unless your organization has configured one or more [global variable sets](/terraform/enterprise/workspaces/variables#scope). HCP Terraform will use `*.auto.tfvars` files if they are present, but you will usually still need to set some workspace-specific variables. +- The execution mode defaults to "Remote," so that runs occur within HCP Terraform's infrastructure instead of on your workstation. +- New workspaces are not automatically connected to a VCS repository and do not have a working directory specified. +- A new workspace's Terraform version defaults to the most recent release of Terraform at the time the workspace was created. + +### Implicit Project Creation + +If you configure the [`workspaces` block](/terraform/cli/cloud/settings#workspaces) to use a [project](/terraform/cli/cloud/settings#project) that does not yet exist in your organization, HCP Terraform will attempt to create a new project with that name when you run `terraform init` and notify you in the command output. + +If you specify both the `project` argument and [`TF_CLOUD_PROJECT`](/terraform/cli/cloud/settings#tf_cloud_project) environment variable, the `project` argument takes precedence. + +## Variables in CLI-Driven Runs + +Remote runs in HCP Terraform use: + +- Run-specific variables set through the command line or in your local environment. Terraform can use shell environment variables prefixed with `TF_VAR_` as input variables for the run, but you must still set all required environment variables, like provider credentials, inside the workspace. +- Workspace-specific Terraform and environment variables set in the workspace. +- Any variable sets applied globally, on the project containing the workspace, or on the workspace itself. +- Terraform variables from any `*.auto.tfvars` files included in the configuration. + +Refer to [Variables](/terraform/enterprise/workspaces/variables) for more details about variable types, variable scopes, variable precedence, and how to set run-specific variables through the command line. + +## Remote Working Directories + +If you manage your Terraform configurations in self-contained repositories, the remote working directory always has the same content as the local working directory. + +If you use a combined repository and [specify a working directory on workspaces](/terraform/enterprise/workspaces/settings#terraform-working-directory), you can run Terraform from either the real working directory or from the root of the combined configuration directory. In both cases, Terraform will upload the entire combined configuration directory. + +## Excluding Files from Upload + +-> **Version note:** `.terraformignore` support was added in Terraform 0.12.11. + +CLI-driven runs upload an archive of your configuration directory +to HCP Terraform. If the directory contains files you want to exclude from upload, +you can do so by defining a [`.terraformignore` file in your configuration directory](/terraform/cli/cloud/settings). + +## Remote Speculative Plans + +You can run speculative plans in any workspace where you have [permission to queue plans](/terraform/enterprise/users-teams-organizations/permissions). Speculative plans use the configuration code from the local working directory, but will use variable values from the specified workspace. + +To run a [speculative plan][] on your configuration, use the `terraform plan` command. The plan will run in HCP Terraform, and the logs will stream back to the command line along with a URL to view the plan in the HCP Terraform UI. + + $ terraform plan + + Running plan in HCP Terraform. Output will stream here. Pressing Ctrl-C + will stop streaming the logs, but will not stop the plan running remotely. + + Preparing the remote plan... + + To view this run in a browser, visit: + https://app.terraform.io/app/hashicorp-learn/docs-workspace/runs/run-cfh2trDbvMU2Rkf1 + + Waiting for the plan to start... + + [...] + + Plan: 1 to add, 0 to change, 0 to destroy. + + Changes to Outputs: + + pet_name = (known after apply) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Remote Applies + +In workspaces that are not connected to a VCS repository, users with [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) can use the CLI to trigger remote applies. Remote applies use the configuration code from the local working directory, but use the variable values from the specified workspace. + +~> **Note:** You cannot run remote applies in workspaces that are linked to a VCS repository, since the repository serves as the workspace’s source of truth. To apply changes in a VCS-linked workspace, merge your changes to the designated branch. + +When you are ready to apply configuration changes, use the `terraform apply` command. HCP Terraform will plan your changes, and the command line will prompt you for approval before applying them. + + $ terraform apply + + Running apply in HCP Terraform. Output will stream here. Pressing Ctrl-C + will cancel the remote apply if it's still pending. If the apply started it + will stop streaming the logs, but will not stop the apply running remotely. + + Preparing the remote apply... + + To view this run in a browser, visit: + https://app.terraform.io/app/hashicorp-learn/docs-workspace/runs/run-Rcc12TkNW1PDa7GH + + Waiting for the plan to start... + + [...] + + Plan: 1 to add, 0 to change, 0 to destroy. + + Changes to Outputs: + + pet_name = (known after apply) + + Do you want to perform these actions in workspace "docs-workspace"? + Terraform will perform the actions described above. + Only 'yes' will be accepted to approve. + + Enter a value: yes + + [...] + + Apply complete! Resources: 1 added, 0 changed, 0 destroyed. + +### Non-Interactive Workflows + +> **Hands On:** Try the [Deploy Infrastructure with HCP Terraform and CircleCI](/terraform/tutorials/automation/circle-ci) tutorial. + +External systems cannot run the traditional apply workflow because Terraform requires console input from the user to approve plans. We recommend using the [API-driven Run Workflow](/terraform/enterprise/run/api) for non-interactive workflows when possible. + +If you prefer to use the CLI in a non-interactive environment, we recommend first running a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) to preview the changes Terraform will make to your infrastructure. Then, use one of the following approaches with the `-auto-approve` flag based on the [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) of your workspace. The [`-auto-approve`](/terraform/cli/commands/apply#auto-approve) flag skips prompting you to approve the plan. + +- **Local Execution:** Save the approved speculative plan and then run `terraform apply -auto-approve` with the saved plan. +- **Remote Execution:** HCP Terraform does not support uploading saved plans for remote execution, so we recommend running `terraform apply -auto-approve` immediately after approving the speculative plan to prevent the plan from becoming stale. + + !> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize the risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Remote Saved Plans + +-> **Version note:** Saved plans require at least Terraform CLI v1.6.0. + +In workspaces that support `terraform apply`, you also have the option of performing the plan and apply as separate steps, using the standard variations of the relevant Terraform commands: + +- `terraform plan -out ` performs and saves a plan. +- `terraform apply ` applies a previously saved plan. +- `terraform show ` (and `terraform show -json `) inspect a plan you previously saved. + +Saved plan runs are halfway between [speculative plans](#remote-speculative-plans) and standard [plan and apply runs](#remote-applies). They allow you to: + +- Perform cheap exploratory plans while retaining the option of applying a specific plan you are satisfied with. +- Perform other tasks in your terminal between the plan and apply stages. +- Perform the plan and apply operations on separate machines (as is common in continuous integration workflows). + +Saved plans become _stale_ once the state Terraform planned them against is no longer valid (usually due to someone applying a different run). In HCP Terraform, stale saved plan runs are automatically detected and discarded. When examining a remote saved plan, the `terraform show` command (without the `-json` option) informs you if a plan has been discarded or is otherwise unable to be applied. + +### File Contents and Permissions + +You can only apply remote saved plans in the same remote HCP Terraform workspace that performed the plan. Additionally, you can not apply locally executed saved plans in a remote workspace. + +In order to abide by HCP Terraform's permissions model, remote saved plans do not use the same local file format as locally executed saved plans. Instead, remote saved plans are a thin reference to a remote run, and the Terraform CLI relies on authenticated network requests to inspect and apply remote plans. This helps avoid the accidental exposure of credentials or other sensitive information. + +The `terraform show -json` command requires [workspace admin permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) to inspect a remote saved plan; this is because the [machine-readable JSON plan format](/terraform/internals/json-format) contains unredacted sensitive information (alongside redaction hints for use by systems that consume the format). The human-readable version of `terraform show` only requires the read runs permission, because it uses pre-redacted information. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Policy Enforcement + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policies are rules that HCP Terraform enforces on Terraform runs. You can use two policy-as-code frameworks to define fine-grained, logic-based policies: Sentinel and Open Policy Agent (OPA). + +If the specified workspace uses policies, HCP Terraform runs those policies against all speculative plans and remote applies in that workspace. Failed policies can pause or prevent an apply, depending on the enforcement level. Refer to [Policy Enforcement](/terraform/enterprise/policy-enforcement) for details. + +For Sentinel, the Terraform CLI prints policy results for CLI-driven runs. CLI support for policy results is not available for OPA. + +The following example shows Sentinel policy output in the terminal. + + $ terraform apply + + [...] + + Plan: 1 to add, 0 to change, 1 to destroy. + + ------------------------------------------------------------------------ + + Organization policy check: + + Sentinel Result: false + + Sentinel evaluated to false because one or more Sentinel policies evaluated + to false. This false was not due to an undefined value or runtime error. + + 1 policies evaluated. + ## Policy 1: my-policy.sentinel (soft-mandatory) + + Result: false + + FALSE - my-policy.sentinel:1:1 - Rule "main" + + Do you want to override the soft failed policy check? + Only 'override' will be accepted to override. + + Enter a value: override + +## Options for Plans and Applies + +[Run Modes and Options](/terraform/enterprise/run/modes-and-options) contains more details about the various options available for plans and applies when you use the CLI-driven workflow. + +## Networking/Connection Issues + +Sometimes during a CLI-driven run, errors relating to network connectivity issues arise. Examples of these kinds of errors include: + +- `Client.Timeout exceeded while awaiting headers` +- `context deadline exceeded` +- `TLS handshake timeout` + +Sometimes there are network problems beyond our control. If you have network errors, verify your network connection is operational. Then, check the following common configuration settings: + +- Determine if any firewall software on your system blocks the `terraform` command and explicitly approve it. +- Verify that you have a valid DNS server IP address. +- Remove any expired TLS certificates for your system. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/install-software.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/install-software.mdx new file mode 100644 index 0000000000..31ff8d5b1c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/install-software.mdx @@ -0,0 +1,111 @@ +--- +page_title: Install software in the HCP Terrafrom run environment +description: >- + Learn how to install Terraform providers, cloud CLIs, or configuration + management tools and software on Terraform Enterprise workers. +source: terraform-docs-common +--- + +# Install software in the run environment + +Terraform relies on provider plugins to manage resources. In most cases, Terraform can automatically download the required plugins, but there are cases where plugins must be managed explicitly. + +In rare cases, it might also be necessary to install extra software on the Terraform worker, such as a configuration management tool or cloud CLI. + +## Installing Terraform Providers + +The mechanics of provider installation changed in Terraform 0.13, thanks to the introduction of the [Terraform Registry][registry] for providers which allows custom and community providers to be installed via `terraform init`. Prior to Terraform 0.13, Terraform could only automatically install providers distributed by HashiCorp. + +### Terraform 0.13 and later + +#### Providers From the Terraform Registry + +The [Terraform Registry][registry] allows anyone to publish and distribute providers which can be automatically downloaded and installed via `terraform init`. + +Terraform Enterprise instances must be able to access `registry.terraform.io` to use providers from the public registry; otherwise, you can install providers using [the `terraform-bundle` tool][bundle]. + +[registry]: https://registry.terraform.io/browse/providers + +#### In-House Providers + +If you have a custom provider that you'd rather not publish in the public Terraform Registry, you have a few options: + +- Add the provider binary to the VCS repo (or manually-uploaded configuration version). Place the compiled `linux_amd64` version of the plugin at `terraform.d/plugins/////linux_amd64`, relative to the root of the directory. + + The source host and namespace will need to match the source given in the `required_providers` block within the configuration, but can otherwise be arbitrary identifiers. For instance, if your `required_providers` block looks like this: + + terraform { + required_providers { + custom = { + source = "my-host/my-namespace/custom" + version = "1.0.0" + } + } + } + + HCP Terraform will be able to use your compiled provider if you place it at `terraform.d/plugins/my-host/my-namespace/custom/1.0.0/linux_amd64/terraform-provider-custom`. + +- Use a privately-owned provider registry service which implements the [provider registry protocol](/terraform/internals/provider-registry-protocol) to distribute custom providers. Be sure to include the full [source address](/terraform/language/providers/requirements#source-addresses), including the hostname, when referencing providers. + +- **Terraform Enterprise only:** Use [the `terraform-bundle` tool][bundle] to add custom providers. + +-> **Note:** Using a [network mirror](/terraform/internals/provider-network-mirror-protocol) to host custom providers for installation is not currently supported in HCP Terraform, since the network mirror cannot be activated without a [`provider_installation`](/terraform/cli/config/config-file#explicit-installation-method-configuration) block in the CLI configuration file. + +### Terraform 0.12 and earlier + +#### Providers Distributed by HashiCorp + +HCP Terraform can automatically install providers distributed by HashiCorp. Terraform Enterprise instances can do this as well as long as they can access `releases.hashicorp.com`. + +If that isn't feasible due to security requirements, you can manually install providers. Use [the `terraform-bundle` tool][bundle] to build a custom version of Terraform that includes the necessary providers, and configure your workspaces to use that bundled version. + +[bundle]: https://github.com/hashicorp/terraform/tree/master/tools/terraform-bundle#installing-a-bundle-in-on-premises-terraform-enterprise + +#### Custom and Community Providers + +To use community providers or your own custom providers with Terraform versions prior to 0.13, you must install them yourself. + +There are two ways to accomplish this: + +- Add the provider binary to the VCS repo (or manually-uploaded configuration version) for any workspace that uses it. Place the compiled `linux_amd64` version of the plugin at `terraform.d/plugins/linux_amd64/` (as a relative path from the root of the working directory). The plugin name should follow the [naming scheme](/terraform/language/v1.1.x/configuration-0-11/providers#plugin-names-and-versions) and the plugin file must have read and execute permissions. (Third-party plugins are often distributed with an appropriate filename already set in the distribution archive.) + + You can add plugins directly to a configuration repo, or you can add them as Git submodules and symlink the executable files into `terraform.d/plugins/`. Submodules are a good choice when many workspaces use the same custom provider, since they keep your repos smaller. If using submodules, enable the ["Include submodules on clone" setting](/terraform/enterprise/workspaces/settings/vcs#include-submodules-on-clone) on any affected workspace. + +- **Terraform Enterprise only:** Use [the `terraform-bundle` tool][bundle] to add custom providers to a custom Terraform version. This keeps custom providers out of your configuration repos entirely, and is easier to update when many workspaces use the same provider. + +## Installing Additional Tools + +### Avoid Installing Extra Software + +Whenever possible, don't install software on the worker. There are a number of reasons for this: + +- Provisioners are a last resort in Terraform; they greatly increase the risk of creating unknown states with unmanaged and partially-managed infrastructure, and the `local-exec` provisioner is especially hazardous. [The Terraform CLI docs on provisioners](/terraform/language/resources/provisioners/syntax#provisioners-are-a-last-resort) explain the hazards in more detail, with more information about the preferred alternatives. (In summary: use Packer, use cloud-init, try to make your infrastructure more immutable, and always prefer real provider features.) +- We don't guarantee the stability of the operating system on the Terraform build workers. It's currently the latest version of Ubuntu LTS, but we reserve the right to change that at any time. +- The build workers are disposable and are destroyed after each use, which makes managing extra software even more complex than when running Terraform CLI in a persistent environment. Custom software must be installed on every run, which also increases run times. + +### Only Install Standalone Binaries + +HCP Terraform does not allow you to elevate a command's permissions with `sudo` during Terraform runs. This means you cannot install packages using the worker OS's normal package management tools. However, you can install and execute standalone binaries in Terraform's working directory. + +You have two options for getting extra software into the configuration directory: + +- Include it in the configuration repository as a submodule. (Make sure the workspace is configured to clone submodules.) +- Use `local-exec` to download it with `curl`. For example: + + ```hcl + resource "aws_instance" "example" { + ami = "${var.ami}" + instance_type = "t2.micro" + provisioner "local-exec" { + command = < **Note:** Terraform Enterprise instances can be configured to allow `sudo` commands during Terraform runs. However, even when `sudo` is allowed, using the worker OS's package tools during runs is still usually a bad idea. You will have a much better experience if you can move your provisioner actions into a custom provider or an immutable machine image. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/manage.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/manage.mdx new file mode 100644 index 0000000000..2594b81dae --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/manage.mdx @@ -0,0 +1,78 @@ +--- +page_title: Manage and view runs in Terraform Enterprise +description: >- + Learn how to view and interact with runs in Terraform Enterprise, and how to + unlock and lock workspaces to prevent new runs. +source: terraform-docs-common +--- + +# Manage and view runs + +Each workspace in HCP Terraform includes a list of its current, pending, and historical runs. You can view and interact with these runs in the UI. You can also lock workspaces to temporarily prevent new runs. + +## API + +Refer to the [Runs API](/terraform/enterprise/api-docs/run) and [lock a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#lock-a-workspace). + +## Navigating Runs + +Go to the workspace and click the **Runs** tab to review a list of all current and past Terraform runs. + +Click a run to go to its details page. The details page contains the following information: + +- The current status of the run. +- The code commit associated with the run. +- How the run initiated, when, and which user initiated it (if applicable). +- A timeline of events related to the run. +- The output from both the `terraform plan` and `terraform apply` commands, if applicable. This output defaults to visible if the command is currently running and hidden if the command has finished. + +## Interacting with Runs + +In workspaces where you have [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions), you can interact with a run at the bottom of its details page. + +The following options are available, depending on the state of the run: + +| Button | Available when: | +| ------------------- | --------------------------------------------------------------------------------------------------------------- | +| Add Comment | Always. | +| Confirm & Apply | A plan needs confirmation. | +| Override & Continue | A soft-mandatory policy failed. Requires permission to manage policy overrides for the organization. | +| Discard Run | A plan needs confirmation or a soft-mandatory policy failed. | +| Cancel Run | A plan or apply is currently running. | +| Force Cancel Run | A plan or apply canceled, but HCP Terraform was unable to end the run. Requires admin access to the workspace. | +| Retry Run | A plan-only run has finished. You can also change which Terraform version to use when retrying a plan-only run. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If a plan needs confirmation (with [manual apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) enabled) or a soft-mandatory policy failed, the run remains paused until a user with appropriate permissions uses these buttons to continue or discard the run. Refer to [Run States and Stages](/terraform/enterprise/run/states) for more details. + +### Canceling Runs + +If a run is currently planning or applying, users with [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) for the workspace can click **Cancel Run** to stop the run before it finishes. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Canceling a run is roughly equivalent to typing `ctrl+c` during a Terraform plan or apply on the CLI. The running Terraform process is sent an INT signal, which instructs Terraform to end its work, update state for any resources that have already been changed, and wrap up in the safest way possible. + +In rare cases, a canceled run can fail to end, continuing to lock the workspace. You can forcefully cancel these runs, which immediately terminates the running Terraform process and unlocks the workspace. + +Force-canceling requires admin access to the workspace because it can have dangerous side-effects, including loss of state and orphaned resources. Additionally, the **Force Cancel Run** button only appears after you click **Cancel Run** and HCP Terraform has time to terminate the run safely. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Locking Workspaces (Preventing Runs) + +You can lock the workspace to temporarily stop runs from proceeding. Locking a workspace requires [permission to lock and unlock the workspace](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions), and requires that the workspace is not currently locked by an in-progress run. + +A lock prevents HCP Terraform from performing any applies in the workspace, and also prevents many kinds of plans. New runs remain in the **Pending** state until the workspace unlocks. + +Locking **does not** affect [plan-only runs](/terraform/enterprise/run/remote-operations#speculative-plans) or the planning stages of [saved plan runs](/terraform/enterprise/run/cli#remote-saved-plans). Terraform allows these types of runs because they can not affect infrastructure resources, do not attempt to lock the workspace themselves, and might provide important information about tasks to perform before removing the lock. Note that you can not _apply_ saved-plan runs while the workspace is locked, and HCP Terraform automatically discards these runs if the workspace's state is changed before they can be applied. Terraform Enterprise does not yet support saved plans. + +HCP Terraform shows the lock status in the workspace's header, next to the **Actions** menu. + +To lock or unlock a workspace, do one of the following: + +- Open the **Actions** menu and select **Lock workspace** or **Unlock workspace**. +- Go to **Settings > Locking**. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/modes-and-options.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/modes-and-options.mdx new file mode 100644 index 0000000000..136e6d374d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/modes-and-options.mdx @@ -0,0 +1,123 @@ +--- +page_title: Run modes and options in Terraform Enterprise +description: >- + Learn about the different run modes and options available in Terraform + Enterprise to customize behavior during runs. +source: terraform-docs-common +--- + +# Run modes and options + +HCP Terraform runs support many of the same modes and options available in the Terraform CLI. + +## Plan and Apply (Standard) + +The default run mode of HCP Terraform is to perform a plan and then apply it. If you have enabled auto-apply, a successful plan applies immediately. Otherwise, the run waits for user confirmation before applying. + +- **CLI:** Use `terraform apply` (without providing a saved plan file). +- **API:** Create a run without specifying any options that select a different mode. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Plan and apply (standard)** as the run type. +- **VCS:** When a workspace is connected to a VCS repository, HCP Terraform automatically starts a standard plan and apply when you add new commits to the selected branch of that repository. + +## Destroy Mode + +[Destroy mode](/terraform/cli/commands/plan#planning-modes) instructs Terraform to create a plan which destroys all objects, regardless of configuration changes. + +- **CLI:** Use `terraform plan -destroy` or `terraform destroy` +- **API:** Use the `is-destroy` option. +- **UI:** Use a workspace's **Destruction and Deletion** settings page. + +## Plan Only/Speculative Plan + +This option creates a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans). The speculative plan shows a set of possible changes and checks them against Sentinel policies, but Terraform can _not_ apply this plan. + +You can create speculative plans with a different Terraform version than the one currently selected for a workspace. This lets you check whether your configuration is compatible with a newer Terraform version without changing the workspace settings. + +Plan-only runs ignore the per-workspace run queue. Plan-only runs can proceed even if another run is in progress, can not become the workspace's current run, and do not block progress on a workspace's other runs. + +- **API:** Set the `plan-only` option to `true` and specify an available terraform version using the `terraform-version` field. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Plan only** as the run type. +- **VCS:** When a workspace is connected to a VCS repository, HCP Terraform automatically starts a speculative plan when someone opens a pull request (or merge request) against the selected branch of that repository. The pull/merge request view in your VCS links to the speculative plan, and you can also find it in the workspace's run list. + +## Saved Plans + +-> **Version note:** Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1.6.0. + +Saved plan runs are very similar to standard plan and apply runs: they perform a plan and then optionally apply it. There are three main differences: + +1. _No wait for planning._ Saved plan runs ignore the per-workspace run queue during their plan and checks. Like plan-only runs, saved plans can begin planning even if another run is in progress, without blocking progress on other runs. +2. _No auto-apply._ Saved plan runs are never auto-applied, even if you enabled auto-apply for the workspace. Saved plans only apply if you confirm them. +3. _Automatic discard for stale plans._ If another run is applied (or the state is otherwise modified) before a saved plan run is confirmed, HCP Terraform automatically discards that saved plan. HCP Terraform may also automatically discard saved plans if they are not confirmed within a few weeks. + +Saved plans are ideal for interactive CLI workflows, where you can perform many exploratory plans and then choose one to apply, or for custom continuous integration workflows where the default run queue behavior isn't suitable. + +- **CLI:** Use `terraform plan -out ` to perform and save a plan, then use `terraform apply ` to apply the saved plan. Use `terraform show ` to inspect a saved plan before applying it. +- **API:** Use the `save-plan` option when creating a run. If you create a new configuration version for a saved plan run, use the `provisional` option so that it will not become the workspace's current configuration version until you decide to apply the run. + +## Allow Empty Apply + +A no-operation (empty) apply enables HCP Terraform to apply a run from a plan that contains no infrastructure changes. During apply, Terraform can upgrade the state version if required. You can use this option to upgrade the state in your HCP Terraform workspace to a new Terraform version. Only some Terraform versions require this, most notably 0.13. + +To make such upgrades easier, empty apply runs will always auto-apply if their plan contains no changes. + +~> **Warning:** HCP Terraform cannot guarantee that a plan in this mode will produce no changes. We recommend checking the plan for drift before proceeding to the apply stage. + +- **API:** Set the `allow-empty-apply` field to `true`. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Allow empty apply** as the run type. + +## Refresh-Only Mode + +> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. + +-> **Version note:** Refresh-only support requires a workspace using at least Terraform CLI v0.15.4. + +[Refresh-only mode](/terraform/cli/commands/plan#planning-modes) instructs Terraform to create a plan that updates the Terraform state to match changes made to remote objects outside of Terraform. This is useful if state drift has occurred and you want to reconcile your state file to match the drifted remote objects. Applying a refresh-only run does not result in further changes to remote objects. + +- **CLI:** Use `terraform plan -refresh-only` or `terraform apply -refresh-only`. +- **API:** Use the `refresh-only` option. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Refresh state** as the run type. + +## Skipping Automatic State Refresh + +The [`-refresh=false` option](/terraform/cli/commands/plan#refresh-false) is used in normal planning mode to skip the default behavior of refreshing Terraform state before checking for configuration changes. + +- **CLI:** Use `terraform plan -refresh=false` or `terraform apply -refresh=false`. +- **API:** Use the `refresh` option. + +## Replacing Selected Resources + +-> **Version note:** Replace support requires a workspace using at least Terraform CLI v0.15.2. + +The [replace option](/terraform/cli/commands/plan#replace-address) instructs Terraform to replace the object with the given resource address. + +- **CLI:** Use `terraform plan -replace=ADDRESS` or `terraform apply -replace=ADDRESS`. +- **API:** Use the `replace-addrs` option. +- **UI:** Click **+ New run** and select the **Plan and apply (standard)** run type. Then click **Additional planning options** to reveal the **Replace resources** option. Type the address of the resource that you want to replace. You can replace multiple resources. + +## Targeted Plan and Apply + +[Resource Targeting](/terraform/cli/commands/plan#resource-targeting) is intended for exceptional circumstances only and should not be used routinely. + +- **CLI:** Use `terraform plan -target=ADDRESS` or `terraform apply -target=ADDRESS`. +- **API:** Use the `target-addrs` option. + +The usual caveats for targeting in local operations imply some additional limitations on HCP Terraform features for remote plans created with targeting: + +- [Sentinel](/terraform/enterprise/policy-enforcement) policy checks for targeted plans will see only the selected subset of resource instances planned for changes in [the `tfplan` import](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) and [the `tfplan/v2` import](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2), which may cause an unintended failure for any policy that requires a planned change to a particular resource instance selected by its address. + +- [Cost Estimation](/terraform/enterprise/cost-estimation) is disabled for any run created with `-target` set, to prevent producing a misleading underestimate of cost due to resource instances being excluded from the plan. + +You can disable or constrain use of targeting in a particular workspace using a Sentinel policy based on [the `tfrun.target_addrs` value](/terraform/enterprise/policy-enforcement/import-reference/tfrun#value-target_addrs). + +## Generating Configuration + +-> **Version note:** Support for `import` blocks and generating configuration requires a workspace using at least Terraform CLI v1.5.0. + +When using [`import` blocks](/terraform/language/import) to import existing resources, Terraform can [automatically generate configuration](/terraform/language/import/generating-configuration) during the plan for any imported resources that don't have an existing `resource` block. This option is enabled by default for runs started from the UI or from a VCS webhook. + +- **CLI:** Use `terraform plan -generate-config-out=generated.tf`. +- **API:** Use the `allow-config-generation` option. + +You can find generated configuration displayed in the plan UI. If you're using the CLI workflow, Terraform will write generated configuration to the file you specify when running `terraform plan`. + +Once Terraform has generated configuration for you, you'll need to review it, incorporate it in your Terraform configuration (including committing it to version control), then run another plan. If you try to directly apply a plan with generated configuration, the run will error. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/remote-operations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/remote-operations.mdx new file mode 100644 index 0000000000..8091309a5e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/remote-operations.mdx @@ -0,0 +1,148 @@ +--- +page_title: Remote operations in Terraform Enterprise +description: >- + Terraform Enterprise runs Terraform operations remotely through the UI, API, + or CLI. Learn how HCP Terraform manages runs. +source: terraform-docs-common +--- + +# Remote operations + +> **Hands-on:** Try the [Get Started — HCP Terraform](/terraform/tutorials/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. + +HCP Terraform provides a central interface for running Terraform within a large collaborative organization. If you're accustomed to running Terraform from your workstation, the way HCP Terraform manages runs can be unfamiliar. + +This page describes the basics of how runs work in HCP Terraform. + +## Remote Operations + +HCP Terraform is designed as an execution platform for Terraform, and can perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment, and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more. + +Terraform runs managed by HCP Terraform are called _remote operations._ Remote runs can be initiated by webhooks from your VCS provider, by UI controls within HCP Terraform, by API calls, or by Terraform CLI. When using Terraform CLI to perform remote operations, the progress of the run is streamed to the user's terminal, to provide an experience equivalent to local operations. + +### Disabling Remote Operations + +[execution_mode]: /terraform/enterprise/workspaces/settings#execution-mode + +Many of HCP Terraform's features rely on remote execution and are not available when using local operations. This includes features like Sentinel policy enforcement, cost estimation, and notifications. + +You can disable remote operations for any workspace by changing its [Execution Mode][execution_mode] to **Local**. This causes the workspace to act only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers. + +### Protecting Private Environments + +[HCP Terraform agents](/terraform/cloud-docs/agents) are a paid feature that allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. The agent polls HCP Terraform or Terraform Enterprise for any changes to your configuration and executes the changes locally, so you do not need to allow public ingress traffic to your resources. Agents allow you to control infrastructure in private environments without modifying your network perimeter. + +HCP Terraform agents also support running custom programs, called _hooks_, during strategic points of a Terraform run. For example, you may create a hook to dynamically download software required by the Terraform run or send an HTTP request to a system to kick off an external workflow. + +## Runs and Workspaces + +HCP Terraform always performs Terraform runs in the context of a [workspace](/terraform/enterprise/run/remote-operations). The workspace serves the same role that a persistent working directory serves when running Terraform locally: it provides the configuration, state, and variables for the run. + +### Configuration Versions + +Each workspace is associated with a particular Terraform configuration, but that configuration is expected to change over time. Thus, HCP Terraform manages configurations as a series of _configuration versions._ + +Most commonly, a workspace is linked to a VCS repository, and its configuration versions are tied to revisions in the specified VCS branch. In workspaces that aren't linked to a repository, new configuration versions can be uploaded via Terraform CLI or via the API. + +### Ordering and Timing + +Each workspace in HCP Terraform maintains its own queue of runs, and processes those runs in order. + +Whenever a new run is initiated, it's added to the end of the queue. If there's already a run in progress, the new run won't start until the current one has completely finished — HCP Terraform won't even plan the run yet, because the current run might change what a future run would do. Runs that are waiting for other runs to finish are in a _pending_ state, and a workspace might have any number of pending runs. + +There are two exceptions to the run queue, which can proceed at any time and do not block the progress of other runs: + +- Plan-only runs. +- The planning stages of [saved plan runs](/terraform/enterprise/run/modes-and-options/#saved-plans). You can only _apply_ a saved plan if no other run is in progress, and applying that plan blocks the run queue as usual. Terraform Enterprise does not yet support this workflow. + +When you initiate a run, HCP Terraform locks the run to a particular configuration version and set of variable values. If you change variables or commit new code before the run finishes, it will only affect future runs, not runs that are already pending, planning, or awaiting apply. + +### Workspace Locks + +When a workspace is _locked,_ HCP Terraform can create new runs (automatically or manually), but those runs do not begin until you unlock the workspace. + +When a run is in progress, that run locks the workspace, as described above under "Ordering and Timing". + +There are two kinds of run operation that can ignore workspace locking: + +- Plan-only runs. +- The planning stages of [saved plan runs](/terraform/enterprise/run/modes-and-options/#saved-plans). You can only _apply_ a saved plan if the workspace is unlocked, and applying that plan locks the workspace as usual. Terraform Enterprise does not yet support this workflow. + +A user or team can also deliberately lock a workspace, to perform maintenance or for any other reason. For more details, see [Locking Workspaces (Preventing Runs)](/terraform/enterprise/run/manage#locking-workspaces-preventing-runs-). + +## Starting Runs + +HCP Terraform has three main workflows for managing runs, and your chosen workflow determines when and how Terraform runs occur. For detailed information, see: + +- The [UI/VCS-driven run workflow](/terraform/enterprise/run/ui), which is the primary mode of operation. +- The [API-driven run workflow](/terraform/enterprise/run/api), which is more flexible but requires you to create some tooling. +- The [CLI-driven run workflow](/terraform/enterprise/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +You can use the following methods to initiate HCP Terraform runs: + +- Click the **+ New run** button on the workspace's page +- Implement VCS webhooks +- Run the standard `terraform apply` command when the CLI integration is configured +- Call [the Runs API](/terraform/enterprise/api-docs/run) using any API tool + +## Plans and Applies + +HCP Terraform enforces Terraform's division between _plan_ and _apply_ operations. It always plans first, then uses that plan's output for the apply. + +In the default configuration, HCP Terraform waits for user approval before running an apply, but you can configure workspaces to [automatically apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) successful plans. Some plans can't be auto-applied, like plans queued by [run triggers](/terraform/enterprise/workspaces/settings/run-triggers) or by users without permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If a plan contains no changes, HCP Terraform does not attempt to apply it. Instead, the run ends with a status of "Planned and finished". The [allow empty apply](/terraform/enterprise/run/modes-and-options#allow-empty-apply) run mode can override this behavior. + +### Speculative Plans + +In addition to normal runs, HCP Terraform can run _speculative plans_ to test changes to a configuration during editing and code review. Speculative plans are plan-only runs. They show possible changes, and policies affected by those changes, but cannot apply any changes. + +Speculative plans can begin without waiting for other runs to finish because they don't affect real infrastructure. HCP Terraform lists past speculative plan runs alongside a workspace's other runs. + +There are three ways to run speculative plans: + +- In VCS-backed workspaces, pull requests start speculative plans, and the VCS provider's pull request interface includes a link to the plan. See [UI/VCS Runs: Speculative Plans on Pull Requests](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) for more details. +- With the [CLI integration](/terraform/cli/cloud) configured, running `terraform plan` on the command line starts a speculative plan. The plan output streams to the terminal, and a link to the plan is also included. +- The runs API creates speculative plans whenever the specified configuration version is marked as speculative. See [the `configuration-versions` API](/terraform/enterprise/api-docs/configuration-versions#create-a-configuration-version) for more information. + +#### Retry a speculative plan in the UI + +If a speculative plan fails due to an external factor, you can run it again using the "Retry Run" button on its page: + +Retrying a plan requires permission to queue plans for that workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) Only failed or canceled plans can be retried. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Retrying the run will create a new run with the same configuration version. If it is a VCS-backed workspace, the pull request interface will receive the status of the new run, along with a link to the new run. + +### Saved Plans + +-> **Version note:** Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1.6.0. + +HCP Terraform also supports saved plan runs. If you have configured the [CLI integration](/terraform/cli/cloud) you can use `terraform plan -out ` to perform and save a plan, `terraform apply ` to apply a saved plan, and `terraform show ` to inspect a saved plan before applying it. You can also create saved plan runs via the API by using the `save-plan` option. + +Saved plan runs affect the run queue differently from normal runs, and can sometimes be automatically discarded. For more details, refer to [Run Modes and Options: Saved Plans](/terraform/enterprise/run/modes-and-options#saved-plans). + +## Planning Modes and Options + +In addition to the normal run workflows described above, HCP Terraform supports destroy runs, refresh-only runs, and several planning options that can modify the behavior of a run. For more details, see [Run Modes and Options](/terraform/enterprise/run/modes-and-options). + +## Run States + +HCP Terraform shows the progress of each run as it passes through each run state (pending, plan, policy check, apply, and completion). In some states, the run might require confirmation before continuing or ending; see [Managing Runs: Interacting with Runs](/terraform/enterprise/run/manage#interacting-with-runs) for more information. + +In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. (Or, if no run is in progress, the state of the most recent completed run.) + +For full details about the stages of a run, see [Run States and Stages][]. + +[Run States and Stages]: /terraform/enterprise/run/states + +## Import + +We recommend using [`import` blocks](/terraform/language/import), introduced in Terraform 1.5, to import resources in HCP Terraform. + +HCP Terraform does not support remote execution for the `terraform import` command. For this command the workspace acts only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers. + +Since `terraform import` runs locally, environment variables defined in the workspace are not available. Any environment variables required by the provider you're importing from must be defined within your local execution scope. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/run-environment.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/run-environment.mdx new file mode 100644 index 0000000000..03955a60e3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/run-environment.mdx @@ -0,0 +1,125 @@ +--- +page_title: Terraform Enterprise's run environment +description: >- + Learn how Terraform Enterprise's run enviornment manages virtual machines, + network access, concurrency for runs, state access authentication, and + environment variables. +source: terraform-docs-common +--- + +# HCP Terraform's run environment + +HCP Terraform is designed as an execution platform for Terraform, and most of its features are based around its ability to perform Terraform runs in a fleet of disposable worker VMs. This page describes some features of the run environment for Terraform runs managed by HCP Terraform. + +## The Terraform Worker VMs + +HCP Terraform performs Terraform runs in single-use Linux virtual machines, running on an x86_64 architecture. + +The operating system and other software installed on the worker VMs is an internal implementation detail of HCP Terraform. It is not part of a stable public interface, and is subject to change at any time. + +Before Terraform is executed, the worker VM's shell environment is populated with environment variables from the workspace, the selected version of Terraform is installed, and the run's Terraform configuration version is made available. + +Changes made to the worker during a run are not persisted to subsequent runs, since the VM is destroyed after the run is completed. Notably, this requires some additional care when installing additional software with a `local-exec` provisioner; see [Installing Additional Tools](/terraform/enterprise/run/install-software#installing-additional-tools) for more details. + +> **Hands-on:** Try the [Upgrade Terraform Version in HCP Terraform](/terraform/tutorials/cloud/cloud-versions) tutorial. + +## Network Access to VCS and Infrastructure Providers + +In order to perform Terraform runs, HCP Terraform needs network access to all of the resources being managed by Terraform. + +If you are using the SaaS version of HCP Terraform, this means your VCS provider and any private infrastructure providers you manage with Terraform (including VMware vSphere, OpenStack, other private clouds, and more) _must be internet accessible._ + +Terraform Enterprise instances must have network connectivity to any connected VCS providers or managed infrastructure providers. + +## Concurrency and Run Queuing + +HCP Terraform uses multiple concurrent worker VMs, which take jobs from a global queue of runs that are ready for processing. (This includes confirmed applies, and plans that have just become the current run on their workspace.) + +If the global queue has more runs than the workers can handle at once, some of them must wait until a worker becomes available. When the queue is backed up, HCP Terraform gives different priorities to different kinds of runs: + +- Applies that will make changes to infrastructure have the highest priority. +- Normal plans have the next highest priority. +- Speculative plans have the lowest priority. + +HCP Terraform can also delay some runs in order to make performance more consistent across organizations. If an organization requests a large number of runs at once, HCP Terraform queues some of them immediately, and delays the rest until some of the initial batch have finished; this allows every organization to continue performing runs even during periods of especially heavy load. + +## State Access and Authentication + +[CLI config file]: /terraform/cli/config/config-file + +[cloud]: /terraform/cli/cloud + +HCP Terraform stores state for its workspaces. + +When you trigger runs via the [CLI workflow](/terraform/enterprise/run/cli), Terraform reads from and writes to HCP Terraform's stored state. HCP Terraform uses [the `cloud` block][cloud] for runs, overriding any existing [backend](/terraform/language/settings/backends/configuration) in the configuration. + +-> **Note:** The `cloud` block is available in Terraform v1.1 and later. Previous versions can use the [`remote` backend](/terraform/language/settings/backends/remote) to configure the CLI workflow and migrate state. + +### Autogenerated API Token + +Instead of using existing user credentials, HCP Terraform generates a unique per-run API token and provides it to the Terraform worker in the [CLI config file][]. When you run Terraform on the command line against a workspace configured for remote operations, you must have [the `cloud` block][cloud] in your configuration and have a user or team API token with the appropriate permissions specified in your [CLI config file][]. However, the run itself occurs within one of HCP Terraform's worker VMs and uses the per-run token for state access. + +The per-run token can read and write state data for the workspace associated with the run, can download modules from the [private registry](/terraform/enterprise/registry), and may be granted access to read state from other workspaces in the organization. (Refer to [cross-workspace state access](/terraform/enterprise/workspaces/state#accessing-state-from-other-workspaces) for more details.) Per-run tokens cannot make any other calls to the HCP Terraform API and are not considered to be user, team, or organization tokens. They become invalid after the run is completed. + +### User Token + +HCP Terraform uses the user token to access a workspace's state when you: + +- Run Terraform on the command line against a workspace that is _not_ configured for remote operations. The user must have permission to read and write state versions for the workspace. + +- Run Terraform's state manipulation commands against an HCP Terraform workspace. The user must have permission to read and write state versions for the workspace. + +Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) for more details about workspace permissions. + +### Provider Authentication + +Runs in HCP Terraform typically require some form of credentials to authenticate with infrastructure providers. Credentials can be provided statically through Environment or Terraform [variables](/terraform/enterprise/workspaces/variables), or can be generated on a per-run basis through [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for certain providers. Below are pros and cons to each approach. + +#### Static Credentials + +##### Pros + +- Simple to setup +- Broad support across providers + +##### Cons + +- Requires regular manual rotation for enhanced security posture +- Large blast radius if a credential is exposed and needs to be revoked + +#### Dynamic Credentials + +##### Pros + +- Eliminates the need for manual rotation of credentials on HCP Terraform +- HCP Terraform metadata - including the run's project, workspace, and run-phase - is encoded into every token to allow for granular permission scoping on the target cloud platform +- Credentials are short-lived, which reduces blast radius of potential credential exposure + +##### Cons + +- More complicated initial setup compared to using static credentials +- Not supported for all providers + +The full list of supported providers and setup instructions can be found in the [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) documentation. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Environment Variables + +HCP Terraform automatically injects the following environment variables for each run: + +| Variable Name | Description | Example | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | +| `TFC_RUN_ID` | A unique identifier for this run. | `run-CKuwsxMGgMd4W7Ui` | +| `TFC_WORKSPACE_NAME` | The name of the workspace used in this run. | `prod-load-balancers` | +| `TFC_WORKSPACE_SLUG` | The full slug of the configuration used in this run. This consists of the organization name and workspace name, joined with a slash. | `acme-corp/prod-load-balancers` | +| `TFC_CONFIGURATION_VERSION_GIT_BRANCH` | The name of the branch that the associated Terraform configuration version was ingressed from. | `main` | +| `TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA` | The full commit hash of the commit that the associated Terraform configuration version was ingressed from. | `abcd1234...` | +| `TFC_CONFIGURATION_VERSION_GIT_TAG` | The name of the tag that the associated Terraform configuration version was ingressed from. | `v0.1.0` | +| `TFC_PROJECT_NAME` | The name of the project used in this run. | `proj-name` | + +They are also available as Terraform input variables by defining a variable with the same name. For example: + +```terraform +variable "TFC_RUN_ID" {} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/states.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/states.mdx new file mode 100644 index 0000000000..a8f444e0a3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/states.mdx @@ -0,0 +1,218 @@ +--- +page_title: Run states and stages in Terraform Enterprise +description: >- + Learn the run stages of Terraform operations. Understanding run stages and + their states can help you follow a run's progress. +source: terraform-docs-common +--- + +# Run states and stages + +Each plan and apply run passes through several stages of action: pending, plan, cost estimation, policy check, apply, and completion. HCP Terraform shows a run's progress through each stage as a run state. + +In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. If no run is in progress, HCP Terraform displays the state of the most recently completed run. + +## The Pending Stage + +_States in this stage:_ + +- **Pending:** HCP Terraform hasn't started action on a run yet. HCP Terraform processes each workspace's runs in the order they were queued, and a run remains pending until every run before it has completed. + +_Leaving this stage:_ + +- If the user discards the run before it starts, the run does not continue (**Discarded** state). +- If the run is first in the queue, it proceeds automatically to the plan stage (**Planning** state). + +## The Fetching Stage + +HCP Terraform may need to fetch the configuration from VCS prior to starting the plan. HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs. + +_States in this stage:_ + +- **Fetching:** If HCP Terraform has not yet fetched the configuration from VCS, the run will go into this state until the configuration is available. + +_Leaving this stage:_ + +- If HCP Terraform encounters an error when fetching the configuration from VCS, the run does not continue (**Plan Errored** state). +- If Terraform successfully fetches the configuration, the run moves to the next stage. + +## The Pre-Plan Stage + +The pre-plan phase only occurs if there are enabled [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) in the workspace that are configured to begin before Terraform creates the plan. HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. The information sent to the external system includes the configuration version of the run. + +All runs can enter this phase, including [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). + +_States in this stage:_ + +- **Pre-plan running:** HCP Terraform is waiting for a response from the configured external system(s). + - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status. + +_Leaving this stage:_ + +- If any mandatory tasks failed, the run skips to completion (**Plan Errored** state). +- If any advisory tasks failed, the run proceeds to the **Planning** state, with a visible warning regarding the failed task. +- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, the run fails if there are two advisory tasks that succeed and one mandatory task that fails. +- If a user canceled the run, the run ends in the **Canceled** state. + +## The Plan Stage + +A run goes through different steps during the plan stage depending on whether or not HCP Terraform needs to fetch the configuration from VCS. HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs. + +_States in this stage:_ + +- **Planning:** HCP Terraform is currently running `terraform plan`. +- **Needs Confirmation:** `terraform plan` has finished. Runs sometimes pause in this state, depending on the workspace and organization settings. + +_Leaving this stage:_ + +- If the `terraform plan` command failed, the run does not continue (**Plan Errored** state). +- If a user canceled the plan by pressing the "Cancel Run" button, the run does not continue (**Canceled** state). +- If the plan succeeded with no changes and neither cost estimation nor Sentinel policy checks will be done, HCP Terraform considers the run complete (**Planned and Finished** state). +- If the plan succeeded and requires changes: + - If cost estimation is enabled, the run proceeds automatically to the cost estimation stage. + - If cost estimation is disabled and [Sentinel policies](/terraform/enterprise/policy-enforcement/sentinel) are enabled, the run proceeds automatically to the policy check stage. + - If there are no Sentinel policies and the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + - If there are no Sentinel policies and HCP Terraform cannot auto-apply the plan, the run pauses in the **Needs Confirmation** state until a user with permission to apply runs takes action. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) If an authorized user approves the apply, the run proceeds to the apply stage. If an authorized user rejects the apply, the run does not continue (**Discarded** state). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Note, if you want to directly integrate third-party tools and services between your plan and apply stages, see [Run Tasks](/terraform/enterprise/workspaces/settings/run-tasks). + +## The Post-Plan Stage + +The post-plan phase only occurs if you configure [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) on a workspace to begin after Terraform successfully completes a plan operation. +All runs can enter this phase, including [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). During this phase, HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. + +-> **Note:** The information sent to the configured external system includes the [JSON output](/terraform/internals/json-format) of the Terraform plan. + +_States in this stage:_ + +- **Post-plan running:** HCP Terraform is waiting for a response from the configured external system(s). + - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`, or the timeout will expire and the task will be assumed to be in the `failed` status. + +_Leaving this stage:_ + +- If any mandatory tasks failed, the run skips to completion (**Plan Errored** state). +- If any advisory tasks failed, the run proceeds to the **Applying** state, with a visible warning regarding the failed task. +- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, if there are two advisory tasks that succeed and one mandatory task that failed, the run fails. If one mandatory task succeeds and two advisory tasks fail, the run succeeds with a warning. +- If a user canceled the run, the run ends in the **Canceled** state. + +## The OPA Policy Check Stage + +This stage only occurs if you enabled [Open Policy Agent (OPA) policies](/terraform/enterprise/policy-enforcement/opa) and runs after a successful `terraform plan` and before Cost Estimation. In this stage, HCP Terraform checks whether the plan adheres to the policies in the OPA policy sets for the workspace. + +_States in this stage:_ + +- **Policy Check:** HCP Terraform is checking the plan against the OPA policy sets. +- **Policy Override:** The policy check finished, but a mandatory policy failed. The run pauses, and Terraform cannot perform an apply unless a user manually overrides the policy check failure. Refer to [Policy Results](/terraform/enterprise/policy-enforcement/view-results) for details. +- **Policy Checked:** The policy check succeeded, and Terraform can apply the plan. The run may pause in this state if the workspace is not set up to auto-apply runs. + +_Leaving this stage:_ + +If any mandatory policies failed, the run pauses in the **Policy Override** state. The run completes one of the following workflows: + +- The run stops and enters the **Discarded** state when a user with [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions#manage-policy-overrides) discards the run. +- The run proceeds to the **Policy Checked** state when a user with [permission to manage policy overrides](/terraform/enterprise/users-teams-organizations/permissions) overrides the failed policy. The **Policy Checked** state means that no mandatory policies failed or that a user performed a manual override. + +Once the run reaches the **Policy Checked** state, the run completes one of the following workflows: + +- The run proceeds to the **Apply** stage if Terraform can automatically apply the plan. An auto-apply requires that the **Auto apply** setting is enabled on the workspace. +- If Terraform cannot automatically apply the plan, the run pauses in the **Policy Checked** state until a user with permission to apply runs takes action. If the user approves the apply, the run proceeds to the **Apply** stage. If the user rejects the apply, the run stops and enters the **Discarded** state. + +## The Cost Estimation Stage + +This stage only occurs if cost estimation is enabled. After a successful `terraform plan`, HCP Terraform uses plan data to estimate costs for each resource found in the plan. + +_States in this stage:_ + +- **Cost Estimating:** HCP Terraform is currently estimating the resources in the plan. +- **Cost Estimated:** The cost estimate completed. + +_Leaving this stage:_ + +- If cost estimation succeeded or errors, the run moves to the next stage. +- If there are no policy checks or applies, the run does not continue (**Planned and Finished** state). + +## The Sentinel Policy Check Stage + +This stage only occurs if [Sentinel policies](/terraform/enterprise/policy-enforcement/sentinel) are enabled. After a successful `terraform plan`, HCP Terraform checks whether the plan obeys policy to determine whether it can be applied. + +_States in this stage:_ + +- **Policy Check:** HCP Terraform is currently checking the plan against the organization's policies. +- **Policy Override:** The policy check finished, but a soft-mandatory policy failed, so an apply cannot proceed without approval from a user with permission to manage policy overrides for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) The run pauses in this state. +- **Policy Checked:** The policy check succeeded, and Sentinel will allow an apply to proceed. The run sometimes pauses in this state, depending on workspace settings. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +_Leaving this stage:_ + +- If any hard-mandatory policies failed, the run does not continue (**Plan Errored** state). +- If any soft-mandatory policies failed, the run pauses in the **Policy Override** state. + - If a user with permission to manage policy overrides, overrides the failed policy, the run proceeds to the **Policy Checked** state. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + - If a user with permission to apply runs discards the run, the run does not continue (**Discarded** state). ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) +- If the run reaches the **Policy Checked** state (no mandatory policies failed, or soft-mandatory policies were overridden): + - If the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + - If the plan can't be auto-applied, the run pauses in the **Policy Checked** state until a user with permission to apply runs takes action. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) The run proceeds to the apply stage if they approve the apply, or does not continue (**Discarded** state) if they reject the apply. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## The Pre-Apply Stage + +The pre-apply phase only occurs if the workspace has [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) configured to begin before Terraform creates the apply. HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. The information sent to the external system includes the configuration version of the run. + +Only confirmed runs can enter this phase. + +_States in this stage:_ + +- **Pre-apply running:** HCP Terraform is waiting for a response from the configured external system(s). + - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status. + +_Leaving this stage:_ + +- If any mandatory tasks failed, the run skips to completion. +- If any advisory tasks failed, the run proceeds to the **Applying** state, with a visible warning regarding the failed task. +- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, the run fails if there are two advisory tasks that succeed and one mandatory task that fails. +- If a user canceled the run, the run ends in the **Canceled** state. + +## The Apply Stage + +_States in this stage:_ + +- **Applying:** HCP Terraform is currently running `terraform apply`. + +_Leaving this stage:_ + +After applying, the run proceeds automatically to completion. + +- If the apply succeeded, the run ends in the **Applied** state. +- If the apply failed, the run ends in the **Apply Errored** state. +- If a user canceled the apply by pressing **Cancel Run**, the run ends in the **Canceled** state. + +## The Post-Apply Stage + +The post-apply phase only occurs if you configure [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) on a workspace to begin after Terraform successfully completes an apply operation. During this phase, HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response. However, unlike other stages in the run task process, a failed outcome does not halt the run since HCP Terraform has already provisioned the infrastructure. + +_States in this stage:_ + +- **Post-apply running:** HCP Terraform is waiting for a response from the configured external system(s). +- External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status. + +_Leaving this stage:_ + +- There are only advisory tasks on this stage. +- If any advisory tasks failed, the run proceeds to the **Applied** state, with a visible warning regarding the failed task. +- If a user cancels the run, the run ends in the **Canceled** state. + +## Completion + +A run is complete if it finishes applying, if any part of the run fails, if there is nothing to do, or if a user chooses not to continue. Once a run completes, the next run in the queue can enter the plan stage. + +_States in this stage:_ + +- **Applied:** The run was successfully applied. +- **Planned and Finished:** `terraform plan`'s output already matches the current infrastructure state, so `terraform apply` doesn't need to do anything. +- **Apply Errored:** The `terraform apply` command failed, possibly due to a missing or misconfigured provider or an illegal operation on a provider. +- **Plan Errored:** The `terraform plan` command failed (usually requiring fixes to variables or code), or a hard-mandatory Sentinel policy failed. The run cannot be applied. +- **Discarded:** A user chose not to continue this run. +- **Canceled:** A user interrupted the `terraform plan` or `terraform apply` command with the "Cancel Run" button. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/ui.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/ui.mdx new file mode 100644 index 0000000000..bf1f468aa0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/run/ui.mdx @@ -0,0 +1,138 @@ +--- +page_title: UI and VCS-driven run workflow in Terraform Enterprise +description: >- + Use Terraform Enterprise's UI and VCS-driven run workflow to automatically + queue runs when merging new commits to the VCS repository branch associated + with a workspace. +source: terraform-docs-common +--- + +# UI and VCS-driven run workflow + +HCP Terraform has three workflows for managing Terraform runs. + +- The UI/VCS-driven run workflow described below, which is the primary mode of operation. +- The [API-driven run workflow](/terraform/enterprise/run/api), which is more flexible but requires you to create some tooling. +- The [CLI-driven run workflow](/terraform/enterprise/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +## Summary + +In the UI and VCS workflow, every workspace is associated with a specific branch of a VCS repo of Terraform configurations. HCP Terraform registers webhooks with your VCS provider when you create a workspace, then automatically queues a Terraform run whenever new commits are merged to that branch of workspace's linked repository. + +HCP Terraform also performs a [speculative plan][] when a pull request is opened against that branch. HCP Terraform posts a link to the plan in the pull request, and re-runs the plan if the pull request is updated. + +[speculative plan]: /terraform/enterprise/run/remote-operations#speculative-plans + +The Terraform code for a normal run always comes from version control, and is always associated with a specific commit. + +## Automatically Starting Runs + +In a workspace linked to a VCS repository, runs start automatically when you merge or commit changes to version control. + +If you use GitHub as your VCS provider and merge a PR changing 300 or more files, HCP Terraform automatically triggers runs for every workspace connected to that repository. The GitHub API has a limit of 300 reported changed files for a PR merge. To address this, HCP Terraform initiates workspace runs proactively, preventing oversight of file changes beyond this limit. + +A workspace is linked to one branch of a VCS repository and ignores changes to other branches. You can specify which files and directories within your repository trigger runs. HCP Terraform can also automatically trigger runs when you create Git tags. Refer to [Automatic Run Triggering](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering) for details. + +-> **Note:** A workspace with no runs will not accept new runs via VCS webhook. At least one run must be manually queued to confirm that the workspace is ready for further runs. + +A workspace will not process a webhook if the workspace previously processed a webhook with the same commit SHA and created a run. To trigger a run, create a new commit. If a workspace receives a webhook with a previously processed commit, HCP Terraform will add a new event to the [VCS Events](/terraform/enterprise/vcs#viewing-events) page documenting the received webhook. + +## Manually Starting Runs + +You can manually trigger a run using the UI. Manual runs let you apply configuration changes when you update variable values but the configuration in version control is unchanged. You must manually trigger an initial run in any new VCS-driven workspace. + +To start a run: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to start a run in. +2. Click **+ New run**, opening the **Start a new run** dialog. +3. Select the run mode and provide an optional message. + +Review the [run modes documentation](/terraform/enterprise/run/modes-and-options) for more detail on supported options. + +Run modes that have a plan phase support debugging mode. This is equivalent to setting the `TF_LOG` environment variable to `TRACE` for this run only. To enable debugging, click **Additional planning options** under the run mode and click **Enable debugging mode**. See [Debugging Terraform](/terraform/internals/debugging) for more information. + +To [replace](/terraform/enterprise/run/modes-and-options#replacing-selected-resources) specific resources as part of a standard plan and apply run, expand the **Additional planning options** section and select the resources to replace. + +Manually starting a run requires permission to queue plans for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If the workspace has a plan that is still in the [plan stage](/terraform/enterprise/run/states#the-plan-stage) when a new plan is queued, you can either wait for it to complete, or visit the **Current Run** page and click **Run this plan now**. Be aware that this action terminates the current plan and unlocks the workspace, which can lead to anomalies in behavior, but can be useful if the plans are long-running and the current plan does not have all the desired changes. + +## Automatically cancel plan-only runs triggered by outdated commits + +Refer to [Automatically cancel plan-only runs triggered by outdated commits](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management) for additional information. + +## Confirming or Discarding Plans + +By default, run plans require confirmation before HCP Terraform will apply them. Users with permission to apply runs for the workspace can navigate to a run that has finished planning and click the "Confirm & Apply" or "Discard Plan" button to finish or cancel a run. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) If necessary, use the "View Plan" button for more details about what the run will change. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +![confirm button](/img/docs/runs-confirm.png) + +Users can also leave comments if there's something unusual involved in a run. + +Note that once the plan stage is completed, until you apply or discard a plan, HCP Terraform can't start another run in that workspace. + +### Auto apply + +If you would rather automatically apply plans that don't have errors, you can [enable auto apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) on the workspace's "General Settings" page. Some plans can't be auto-applied, like plans queued by [run triggers](/terraform/enterprise/workspaces/settings/run-triggers) or by users without permission to apply runs. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Speculative Plans on Pull Requests + +To help you review proposed changes, HCP Terraform can automatically run [speculative plans][speculative plan] for pull requests or merge requests. + +### Viewing Pull Request Plans + +You can view speculative plans in a workspace's list of normal runs. Additionally, HCP Terraform adds a link to the run in the pull request itself, along with an indicator of the run's status. + +A single pull request can include links to multiple plans, depending on how many workspaces connect to the destination branch. If you update a pull request, HCP Terraform performs new speculative plans and update the links. + +Although any contributor to the repository can see the status indicators for pull request plans, only members of your HCP Terraform organization with permission to read runs for the affected workspaces can click through and view the complete plan output. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Rules for Triggering Pull Request Plans + +Whenever a pull request is _created or updated,_ HCP Terraform checks whether it should run speculative plans in workspaces connected to that repository, based on the following rules: + +- Only pull requests that originate from within the same repository can trigger speculative plans. + + To avoid executing malicious code or exposing sensitive information, HCP Terraform doesn't run speculative plans for pull requests that originate from forks of a repository. + + -> **Note:** On Terraform Enterprise, administrators can choose to allow speculative plans on pull requests that originate from forks. To learn more about this setting, refer to the [general settings documentation](/terraform/enterprise/admin/application/general#allow-speculative-plans-on-pull-requests-from-forks) + +- Pull requests can only trigger runs in workspaces where automatic speculative plans are allowed. You can [disable automatic speculative plans](/terraform/enterprise/workspaces/settings/vcs#automatic-speculative-plans) in a workspace's VCS settings. + +- A pull request will only trigger speculative plans in workspaces that are connected to that pull request's destination branch. + + The destination branch is the branch that a pull request proposes to make changes to; this is often the repository's main branch, but not always. + +- If a workspace is configured to only treat certain directories in a repository as relevant, pull requests that don't affect those directories won't trigger speculative plans in that workspace. For more information, see [VCS settings: automatic run triggering](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering). + + -> **Note:** If HCP Terraform skips a plan because the changes weren't relevant, it will still post a passing commit status to the pull request. + +- HCP Terraform does not update the status checks on a pull request with the status of an associated apply. This means that a commit with a successful plan but an errored apply will still show the passing commit status from the plan. + +### Contents of Pull Request Plans + +Speculative plans for pull requests use the contents of the head branch (the branch that the PR proposes to merge into the destination branch), and they compare against the workspace's current state at the time of the plan. This means that if the destination branch changes significantly after the head branch is created, the speculative plan might not accurately show the results of accepting the PR. To get a more accurate view, you can rebase the head branch onto a more recent commit, or merge the destination branch into the head branch. + +## Testing Terraform Upgrades with Speculative Plans + +You can start a new [speculative plan][speculative plan] in the UI with the workspace's current configuration version and any Terraform version available to the organization. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to try a new Terraform version in. +2. Click **+ New run**. +3. Select **Plan only** as the run type. +4. Select a version from the **Choose Terraform version** menu. The speculative plan will use this version without changing the workspace's settings. +5. Click **Start run**. + +If the run is successful, you can change the workspace's Terraform version and [upgrade the state](/terraform/enterprise/workspaces/state#upgrading-state). + +## Speculative Plans During Development + +You can also use the CLI to run speculative plans on demand before making a pull request. Refer to the [CLI-driven run workflow](/terraform/enterprise/run/cli#remote-speculative-plans) for more details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/attributes.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/attributes.mdx new file mode 100644 index 0000000000..3023a3ec45 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/attributes.mdx @@ -0,0 +1,81 @@ +--- +page_title: SAML user attributes reference for Terraform Enterprise +description: Terraform Enterprise updates an account with data from SAML user attributes when a new user logs in. Learn how SAML user attributes map to Terraform Enterprise user data. +--- + +# SAML User Attributes Reference + +The following SAML attributes correspond to properties of a Terraform Enterprise user account. When a new or existing user logs in, their account info will be updated with data from these attributes. + +## Username + +If Username is specified, Terraform Enterprise will assign that username to the user instead of using an automatic name [based on their email address](/terraform/enterprise/saml/login). When the username is already taken or is invalid, login will still complete, and the existing or default value will be used instead. + +```xml + + + new-username + + +``` + +## SiteAdmin + +If the SiteAdmin attribute is present, the system will grant or revoke [site admin access](/terraform/enterprise/application-administration/admin-access) for the user. Site admin access can be also be granted or revoked in the [MemberOf attribute](#memberof); however the SiteAdmin attribute is the recommended method of managing access and will override the other value. + +```xml + + + false + + +``` + +## MemberOf + +Team membership is specified in the MemberOf attribute. (If desired, you can [configure a different name](/terraform/enterprise/saml/team-membership) for the team membership attribute.) + +Teams can be specified in separate AttributeValue items: + +```xml + + + devs + reviewers + + +``` + +or in one AttributeValue as a comma-separated list: + +```xml + + + list,of,roles + + +``` + +There is a special-case role `site-admins` that will add a user as a site admin to your Terraform Enterprise instance. + +```xml + + + site-admins + devs + + +``` + +## IsServiceAccount + +If the `IsServiceAccount` (case-sensitive) attribute is present and `true` (case-insensitive), the system will mark the user as a service account. +This will ensure API tokens created for this user will not expire as normal user account tokens expire when reaching the API token session timeout. + +```xml + + + true + + +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/configuration.mdx new file mode 100644 index 0000000000..0448608d6d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/configuration.mdx @@ -0,0 +1,73 @@ +--- +page_title: Configure Terraform Enterprise as the SAML service provider +description: >- + Learn how to configure Terraform Enterprise as the service provider (SP) when integrating with a SAML identity provider for authentication and authorization. +--- + +# Configure Terraform Enterprise as the SAML service provider + +This topic describes how to configure Terraform Enterprise as the SAML service provider (SP). SAML is an XML-based standard for authentication and authorization. Terraform Enterprise can act as a service provider (SP), also called a relying party, with your internal SAML identity provider (IdP). + +## Overview + +Complete the following steps to configure Terraform Enterprise to authenticating and authorizing users with SAML. + +1. Configure Terraform Enterprise as the service provider (SP). The SP also sometimes referred to as relying party (RP). +1. Configure the SAML identity provider (IdP). For instructions for specific IdPs, refer to [Identity Provider Configuration](/terraform/enterprise/saml/idp-configuration). + +Refer to the [Admin Settings API](/terraform/enterprise/api-docs/admin/settings) documentation for instructions on how to configure SAML using the API. + +## Requirements + +Only Terraform Enterprise users with the site-admin permission can modify SAML settings. For more information about site admins, refer to [Site Administration Permissions](/terraform/enterprise/users-teams-organizations/users#site-admin-permissions). + +Prior to activating SAML, we recommend that you create a [non-SSO admin account for recovery](/terraform/enterprise/saml/troubleshooting#create-a-non-sso-admin-account-for-recovery) to ensure that you are able to log in as an admin in case of error. + +Terraform Enterprise supports the SAML 2.0 standard. + +## Configure Terraform Enterprise as the SP + +1. Open your user icon menu and click **Site Admin** or go directly to `https:///app/admin/saml`. +1. Specify values for the SAML settings and click **Save SAML Settings**. Refer to [SAML Configuration Settings Reference](#saml-configuration-settings-reference) for details. + +## Configure the SAML Identity Provider + +Configure the following values in the SAML Identity Provider (IdP): + +1. **Audience**: `https:///users/saml/metadata` +1. **Recipient**: `https:///users/saml/auth` +1. **ACS (Consumer) URL**: `https:///users/saml/auth` + +The SAML metadata document is available at `https:///users/saml/metadata.xml` + +## SAML Configuration Settings Reference + +You can configure the following settings to configure Terraform Enterprise as the SP when integrating with a SAML identity provider. + +### SAML Settings + +- **Enable SAML single sign-on**: This checkbox must be enabled. + +### Identity Provider Settings + +- **Single Sign-On URL**: The HTTP(S) endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. +- **Single Log-Out URL**: The HTTP(s) endpoint on your IdP for single logout requests. This value is provided by your IdP configuration. Single Logout is not yet supported. +- **IdP Certificate**: The PEM encoded X.509 Certificate as provided by the IdP configuration. + +-> **Note:** When reconfiguring the IdP certificate, Terraform Enterprise will retain the old IdP certificate to allow for a rotation period. When you are sure that the new certificate is functioning correctly, you must explicitly remove the old IdP certificate. A button labeled "Revoke old IDP certificate" will appear below the IdP Certificate field if you are in a rotation period. You can also remove the old certificate via an [API endpoint](/terraform/enterprise/api-docs/admin/settings#revoke-previous-saml-idp-certificate). + +### Attributes + +- **Username Attribute Name**: (default: `Username`) The name of the SAML attribute that determines the Terraform Enterprise username for a user logging in via SSO. +- **Site Admin Attribute Name**: (default: `SiteAdmin`) The name of the SAML attribute that determines whether a user has site-admin permissions. The value of this attribute in the SAML assertion must be a boolean. Site admins can manage settings and resources for the entire Terraform Enterprise instance; see [Administering Terraform Enterprise][admin] for details. +- **Team Attribute Name**: (default: `MemberOf`) The name of the SAML attribute that determines [team membership](/terraform/enterprise/saml/team-membership). The value of this attribute in the SAML assertion must be either a string containing a comma-separated list of team names or separate [AttributeValue items](/terraform/enterprise/saml/attributes#memberof). Team membership mapping is case-sensitive. + +### Team Membership Mapping + +- **Site Admin Role**: (default: `site-admins`; make blank to disable) An alternate way of managing site-admin permissions; if a role with this name is present in the value of the Team Attribute Name attribute, the user is an admin. + + We recommend using the "site admin attribute name" setting instead. If you are using the site admin attribute, you can disable "site admin role" by deleting its value. + +### User Session + +- **API Token Session Timeout**: (default: `1209600` seconds, or 14 days) The duration of time (in seconds) for which Terraform Enterprise will accept [a user's API token](/terraform/enterprise/users-teams-organizations/users#api-tokens) before requiring the user to log in again. For more details about this behavior, see [API Token Expiration](/terraform/enterprise/saml/login#api-token-expiration). \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/aad.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/aad.mdx new file mode 100644 index 0000000000..c5052c6d6d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/aad.mdx @@ -0,0 +1,87 @@ +--- +page_title: >- + Configure Azure Active Directory as the identity provider Terraform Enterprise +description: >- + Learn how to use Azure Active Directory as the identify provider for Terraform Enterprise when setting up single-sign on (SSO) over SAML. +--- + +# Configure an Azure Active Directory Identity Provider + +Follow these steps to configure Azure Active Directory (AAD) as the identity provider (IdP) for Terraform Enterprise. + +-> **Note:** This guide assumes you have an appropriate licensing agreement for Azure Active Directory that supports non-gallery application single sign-on. + +## Configure a New AAD Non-Gallery Application + +1. In the Azure Active Directory portal, navigate to **Enterprise Applications** and select **New application**. + +1. Select **Non-gallery application**. Provide a name for the application and click **Add**. AAD automatically redirects to your new application's settings. + +1. Navigate to **Single sign-on** and select **SAML**. + +1. Click the pencil icon in **Basic SAML Configuration** and configure these settings: + - **Identifier (Entity ID):** `https:///users/saml/metadata`, which is **Metadata (audience) URL** in TFE's SAML settings. + - **Reply URL (Assertion Consumer Service URL):** `https:///users/saml/auth`, which is **ACS consumer (recipient) URL** in Terraform Enterprise's SAML settings. + - **Sign on URL:** `https:///` + +1. In the **User Attributes & Claims** section, click the pencil icon and configure these items: + - **Name Identifier value:** `user.mail` + +1. In the **Manage user claim** section, configure a user claim to map the team a user belongs to: + - **Name:** `MemberOf`. This name is the default for TFE's group [attribute](/terraform/enterprise/saml/attributes). You can change this attribute's name in [TFE's SAML settings](/terraform/enterprise/saml/configuration) if necessary. + - **Source attribute:** (drop-down): `user.assignedroles`. This action creates custom roles in your Azure Active Directory that you use to map users and groups to Terraform Enterprise teams. + +1. In the **SAML Signing Certificate** section, download the signing certificate in `base64` format. + +1. In the **Set up <ABD App Name>** section, copy these URLs to enter in your Terraform Enterprise configuration to link Terraform Enterprise to AAD: + +1. In the **Set up <ABD App Name>** section, copy these URLs. You need them to link Terraform Enterprise to Azure Active Directory. + - **Login URL:** + - **Logout URL:** + +1. Navigate to `https:///app/admin/saml` and configure these settings: + - **Enable SAML single sign-on** (check box): enabled. + - **Single Sign-On URL:** Enter the login url. + - **Single Log-out URL:** Enter the logout url. + - **IDP Certificate:** Enter the contents of the PEM (`base64`) encoded X.509 certificate. + +## Configure Custom Roles for Team Membership Mapping + +1. Create teams in Terraform Enterprise. Refer to [Terraform Enterprise Team Membership](/terraform/enterprise/saml/team-membership) for more information. + +1. Return to the Azure Portal, and navigate to the **App registrations** page. + +1. Go to the **Enterprise applications* page, select your Terraform Enterprise application, and then select **Manifest** in the sidebar. + +1. In the manifest editor, locate the **appRoles** block. This block is where you add additional roles that map users and groups to teams in Terraform. + +1. Leave any automatically generated role GUIDs with their default values. Add new roles after the system roles. The new roles must contain a unique GUID value for the ID value of the new role. You can use a tool such as [GUID Generator](https://www.guidgenerator.com) to create the GUIDs for these new roles. + +1. Click **Save** to add the roles. + + -> **Note:** You can add as many roles as your organization needs, such as the `site-admins` role. Azure AD sends the value of these roles as the claim value in the SAML response. + + Example role configuration that creates a new role named **Dev**: + + ```json + { + "allowedMemberTypes": [ + "User" + ], + "displayName": "Dev", + "id": "d1c2ade8-98f8-45fd-aa4a-6d06b947c66f", + "isEnabled": true, + "description": "Dev Team", + "value": "Dev" + } + ``` + +1. Navigate to **Enterprise applications** and select the app you created for TFE. In the sidebar, under the **Manage** heading, select **Users and Groups**. You can enable access to Terraform Enterprise by adding either users or groups to your application. During the process of adding users or groups, you select a role to assign to the user or group. Select the role that matches the user or groups Terraform Enterprise team. + +1. Navigate to **Enterprise applications** and select the app you created for Terraform Enterprise. + +1. Select **Users and Groups** in the sidebar, under the **Manage** heading. You can enable access to Terraform Enterprise by adding either users or groups to your application. During the process of adding users or groups, you select a role to assign to the user or group. + +1. Select the role that matches the user or groups Terraform Enterprise team. + +Once you add users, the initial configuration is complete, and they can begin logging into Terraform Enterprise with their AAD username and password. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/adfs.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/adfs.mdx new file mode 100644 index 0000000000..d09ffdd7f1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/adfs.mdx @@ -0,0 +1,110 @@ +--- +page_title: Configure ADFS as the identify provider for Terraform Enterprise +description: >- + Learn how to use Active Directory Federated Services (ADFS) as the identify provider for Terraform Enterprise when setting up single-sign on (SSO) over SAML. +--- + +# Configure an ADFS Identity Provider + +This guide explains how to configure Active Directory Federated Services (ADFS) in order to use it as an Identity Provider (IdP) for Terraform Enterprise's SAML authentication feature. The screenshots below were taken on Windows Server 2016, and the UI may not look the same on previous Windows versions. + +## Requirements + +Install and configure ADFS before completing these instructions. + +## Gather ADFS information + +1. On the ADFS server, start the Server Manager. + ![saml\_0](/img/docs/saml_0.png) +1. Click "Tools" -> "AD FS Management" + .![saml\_1](/img/docs/saml_1.png) +1. Expand the `Service` object and click "Endpoints". + ![saml\_2](/img/docs/saml_2.png) +1. Make a note of the `URL Path` for Type `SAML 2.0/WS-Federation`. (If you are using the default settings, this will be `/adfs/ls/`.) +1. Switch from "Endpoints" to "Certificates" and choose the one under `Token-signing`. + ![saml\_3](/img/docs/saml_3.png) +1. Right click "View Certificate". + ![saml\_5](/img/docs/saml_5.png) +1. In the Certificate dialog, select the Details tab and click "Copy to File". + ![saml\_6](/img/docs/saml_6.png) +1. In the Certificate Export Wizard, click "Next", select "Base-64 encoded X.509 (.CER)" and click "Next" again. + ![saml\_8](/img/docs/saml_8.png) +1. Pick a location to save the file and click "Next". + ![saml\_9](/img/docs/saml_9.png) +1. Review the settings and click "Finish". + ![saml\_10](/img/docs/saml_10.png) + +## Configure Terraform Enterprise + +1. Visit `https:///app/admin/saml`. +1. Set "Single Sign-on URL" to `https:///`, using the path you noted above in step 4. +1. Set "Single Log-out URL" to `https:///?wa=wsignout1.0` (note that this is the same path with an additional URL parameter). +1. Paste the contents of the saved certificate in "IDP Certificate". +1. Scroll to the bottom of the screen and click "Save SAML Settings". + +## Configure ADFS + +### Configure the Relying Party (RP) Trust + +1. On the ADFS server, start the Server Manager. + ![saml\_0](/img/docs/saml_0.png) +1. Click "Tools" -> "AD FS Management". + ![saml\_1](/img/docs/saml_1.png) +1. Right-click "Relying Party Trusts" and then click "Add Relying Party Trust". + ![saml\_11](/img/docs/saml_11.png) +1. In the Add Relying Party Trust Wizard, select "Claims aware" and click "Start". + ![saml\_12](/img/docs/saml_12.png) +1. Next, select "Import data about the relying party published online or on a local network", and in the text box, enter `https:///users/saml/metadata`. + ![saml\_13](/img/docs/saml_13.png) +1. Click "Next", type a display name used to identify the RP trust, and click "Next" again. + ![saml\_14](/img/docs/saml_14.png) +1. In the "Choose Access Control Policy" screen, choose one that matches your security policy, and click "Next". + ![saml\_15](/img/docs/saml_15.png) +1. Review the settings and click "Next". + ![saml\_16](/img/docs/saml_16.png) +1. Finally, make sure "Configure claims issuance policy for this application" is checked and click "Close". This opens the Claim Issuance Policy editor for the RP trust just configured. + ![saml\_17](/img/docs/saml_17.png) + +### Configure Claim Issuance + +#### LDAP Attributes as Claims + +1. Click "Add Rule", and then select "Send LDAP Attributes as Claims" from the `Claim rule template` dropdown. Click "Next". + +1. Set a name used to identify the claim rule. + +1. Set the attribute store to "Active Directory". + - From the `LDAP Attribute` column, select "E-Mail Addresses". + - From the `Outgoing Claim Type`, select "E-Mail Address". + ![saml\_19](/img/docs/saml_19.png) + +1. Click "Finish". + +#### Transform Incoming Claims + +4. Click "Add Rule", and then select "Transform an Incoming Claim" from the `Claim rule template` dropdown. Click "Next". + ![saml\_22](/img/docs/saml_22.png) +4. Set a name used to identify the claim rule. + +- Select "E-mail Address" as the `Incoming Claim Type`. +- Select "Name ID" as the `Outgoing Claim Type`. +- Select "Email" for `Outgoing Name ID Format`. + ![saml\_23](/img/docs/saml_23.png) + +6. Click "Finish". + +#### Send Group Membership as a Claim + +7. Click "Add Rule", and then select "Send Group Membership as a Claim" from the `Claim rule template` dropdown. Click "Next". +7. Click "Browse" and locate the AD User group that contains all Terraform Enterprise admins. + ![saml\_26](/img/docs/saml_26.png) + +- Set `Outgoing claim type` to `MemberOf`. +- Set `Outgoing claim value` to `site-admins`. + ![saml\_27](/img/docs/saml_27.png) + +9. Click "Finish". + +## Test configured SAML login + +At this point SAML is configured. Follow [these instructions to log in](/terraform/enterprise/saml/login) to Terraform Enterprise. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/index.mdx new file mode 100644 index 0000000000..f79ac064c1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/index.mdx @@ -0,0 +1,84 @@ +--- +page_title: Sample authentication request and response for a SAML identity provider +description: >- + You can enable Terraform Enterprise to authenticate and authorize users over SAML single sign-on. Review a sample SAML request and response to validate your SSO. +--- + +# Sample SAML Authentication Request and Response + +This topic contains an example request from Terraform Enterprise before sign-on and the response from the identity provider after sign-on. Refer to the following topics for instructions on how to configure single sign-on for specific identity providers (IdP): + +- [ADFS](/terraform/enterprise/saml/idp-configuration/adfs) +- [Azure Active Directory](/terraform/enterprise/saml/idp-configuration/aad) +- [Okta](/terraform/enterprise/saml/idp-configuration/okta) +- [OneLogin](/terraform/enterprise/saml/idp-configuration/onelogin) + +## Example AuthnRequest + +```xml + + https://app.terraform.io/users/saml/metadata + + +``` + +## Example SAMLResponse + +```xml + + https://app.terraform.io/saml/metadata/1 + + + + + https://app.onelogin.com/saml/metadata/1 + + + + + + + + + + + 8xMTvqWoOpBMP990fzsoW2HWFVw= + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + + + user@example.com + + + + + + https://app.terraform.io/users/saml/metadata + + + + + urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport + + + + + new-username + + + false + + + devs + reviewers + + + + +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/okta.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/okta.mdx new file mode 100644 index 0000000000..43f360bda1 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/okta.mdx @@ -0,0 +1,145 @@ +--- +page_title: Configure Okta as the identity provider for Terraform Enterprise +description: >- + Learn how to use Okta as the identity provider for Terraform Enterprise when setting up single-sign on (SSO) over SAML. +--- + +# Configure an Okta Identity Provider + +> **Hands-on:** Try the [Enable Single Sign On (SSO) in Terraform Enterprise](/terraform/tutorials/enterprise/enable-sso-saml-tfe-okta) tutorial. + +Follow these steps to configure Okta as the identity provider (IdP) for Terraform Enterprise. + +## Configure a New Okta SAML Application + +1. In Okta's web interface, go to the **Applications** tab and click **Create App Integration**. + +1. Select **SAML 2.0** as the sign on method, and then click **Next**. + +1. In the **General Settings** page, enter `Terraform Enterprise`, optionally add an app logo, then click **Next**. + +1. In the **SAML Settings** section, configure the following settings with the specified values: + + | Okta Field | Terraform Enterprise SAML Field | Value | + | --------------------------------------------------------------------- | ------------------------------- | -------------------------------------------- | + | **Single sign on URL** | ACS Consumer (Recipient) URL | `https:///users/saml/auth` | + | **Use the SSO URL for Recipient URL and Destination URL** (checkbox) | | `enabled` | + | **Audience URI (SP Entity ID)** | Metadata (Audience) URL | `https:///users/saml/metadata` | + | **Name ID format** (drop-down) | | EmailAddress | + | **Application username** | | Email | + + ~> **Note:** The identity provider software uses the SSO URL during authentication. It is different from the [Login URL][login_url] that users visit to sign in to Terraform Enterprise. + + The full name for the **Name ID format** in the SAML specification is `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. + + You can also choose `Email Prefix` for the application username. + +1. In the **SAML Settings** section, optionally configure a site admin permissions attribute statement. This statement determines which users can administer the entire Terraform Enterprise instance. Refer to [Administering Terraform Enterprise](/terraform/enterprise/application-administration) for more information about site admin permissions. Under the **Attribute Statements (Optional)** header, configure a statement as follows: + + | Field | Value | Description | + | --------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **Name** | `SiteAdmin` | This is the default name for TFE's site admin [attribute][]. You can change the name of this attribute in [TFE's SAML settings](/terraform/enterprise/saml/configuration) if necessary. | + | **Name Format** (drop-down) | Basic | | + | **Value** | | An [Okta expression](https://developer.okta.com/docs/reference/okta-expression-language/) that will evaluate to a boolean: `true` for every user who should have site admin permissions, but `false` for any users who should **not** have site admin permissions. The exact expression depends on the user properties you use to manage admin permissions. | + +1. Configure a group attribute statement to report which teams a user belongs to. Under the **Group Attribute Statements (Optional)** header, configure the statement as follows: + + | Field | Value | Description | + | --------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **Name** | `MemberOf` | This is the default name for TFE's group [attribute][]. You can change the name of this attribute in [TFE's SAML settings](/terraform/enterprise/saml/configuration) if necessary. | + | **Name Format** (drop-down) | Basic | | + | **Filter** | | A filter type and filter value that will match all of the relevant groups that each user belongs to. The exact filter expression depends on how your Okta groups are configured, and which subset of groups you want to expose to TFE. Note that Terraform Enterprise ignores group names that do not correspond to existing Terraform Enterprise teams. Refer to [Team Membership Mapping](/terraform/enterprise/saml/team-membership) for more details. | + +1. Click **Preview the SAML Assertion** and make sure it matches your expectations. Click **Next**. + +1. Select **I'm an Okta customer adding an internal app**, and then click **Finish**. + +1. Finish configuring the SAML app in Okta, and then copy the provided endpoint URLs and certificate to your Terraform Enterprise SAML settings at `https:///app/admin/saml` (example below). Terraform Enterprise requires a single sign-on URL, a single log-out URL, and a PEM (base64) encoded X.509 certificate. + +[attribute]: /terraform/enterprise/saml/attributes + +[login_url]: /terraform/enterprise/saml/login + +## Example SAMLResponse + +```xml + + + http://www.okta.com/1 + + + + + + + + + + + + + 000000000000000000000000000= + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + + + + + + http://www.okta.com/1 + + + + + + + + + + + + + 000000000000000000000000000= + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + + + user@example.com + + + + + + + https://example.com/users/saml/metadata + + + + + urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport + + + + + new_username + + + devs + reviewers + + + + +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/onelogin.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/onelogin.mdx new file mode 100644 index 0000000000..d711a17f4b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/idp-configuration/onelogin.mdx @@ -0,0 +1,93 @@ +--- +page_title: Configure OneLogin as the identity provider for Terraform Enterprise +description: >- + Learn how to use OneLogin as the identity provider for Terraform Enterprise when setting up single-sign on (SSO) over SAML. +--- + +# Configure a OneLogin Identity Provider + +Follow these steps to configure OneLogin as the identity provider (IdP) for Terraform Enterprise. + +1. Add a OneLogin app by going to Apps > Add Apps then searching for "SAML Test Connector (IdP)". +1. In the "Info" tab, enter an app name for Terraform Enterprise in the "Display Name" field. + ![image](/img/docs/sso-onelogin-info.png) +1. In the "Configuration" tab, configure the service provider audience and recipient URLs. These are shown in your Terraform Enterprise SAML settings at `https:///app/admin/saml`. + ![image](/img/docs/sso-onelogin-configuration.png) +1. In the "Parameters" tab, map the NameId and MemberOf parameters. + ![image](/img/docs/sso-onelogin-parameters.png) + ![image](/img/docs/sso-onelogin-parameters-memberof.png) +1. In the "SSO" tab, copy the endpoint URLs and certificate, then paste them into your Terraform Enterprise SAML settings at `https:///app/admin/saml` (use the certificate's "View Details" link to copy its PEM-encoded text representation). + ![image](/img/docs/sso-onelogin-sso.png) + ![image](/img/docs/sso-onelogin-sso-certificate.png) +1. In the "Access" tab, enable access for specific roles. + ![image](/img/docs/sso-onelogin-access.png) +1. In the "Users" tab, add users and specify their roles. + ![image](/img/docs/sso-onelogin-users-fields.png) + ![image](/img/docs/sso-onelogin-users.png) + +## Terraform Enterprise SAML SSO settings + +Verify the endpoint URLs, certificate, and attribute mappings are correct in the SAML SSO settings. + +## Additional Resources + +[Create Mappings to Automatically Assign Roles to Users](https://onelogin.service-now.com/kb_view_customer.do?sysparm_article=KB0010625) + + +## Example SAMLResponse + +```xml + + https://example.com/saml/metadata/1 + + + + + https://app.onelogin.com/saml/metadata/1 + + + + + + + + + + + 000000000000000000000000000= + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000== + + + + + user@example.com + + + + + + https://example.com/users/saml/metadata + + + + + urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport + + + + + new-username + + + devs + reviewers + + + + +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/login.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/login.mdx new file mode 100644 index 0000000000..bc4287221a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/login.mdx @@ -0,0 +1,18 @@ +--- +page_title: Log into Terraform Enterprise with SAML +description: >- + Log into Terrafrom Enterprise after configuring SAML. Learn how to visit the login page and how admins can change the user API + token session timeout. +--- + +# Log into Terraform Enterprise with SAML + +Once you configure SAML, Terraform users can visit `https:///session` to login. + +Users can follow the link to complete the SAML login process with the identity provider. If they log in for the first time, Terraform Enterprise creates an account for them. Their username auto-generates from their email address using the text before the `@`. The username only contains alphanumeric characters, `-`, or `_`. All invalid characters convert to `_`. + +## API Token Expiration + +When you initially enable SAML or when a user's SAML-authenticated web session expires, existing user API tokens also temporarily disable until they reauthenticate at `https:///session`. This arrangement is because Terraform Enterprise relies on your identity provider for [team membership mapping](/terraform/enterprise/saml/team-membership) and a user might have been added to or removed from some teams since their session expired. This restriction only affects user tokens, not [team or organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens). + +The API token session timeout is a site-wide setting that is configurable in the admin settings at `https:///app/admin/saml`. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/team-membership.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/team-membership.mdx new file mode 100644 index 0000000000..6a4b43de68 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/team-membership.mdx @@ -0,0 +1,44 @@ +--- +page_title: Enable the SAML identity provider to control team membership mapping +description: You can enable the SAML IdP to control team membership mapping. Learn how to automatically add users to teams based on their SAML assertion. +--- + +# Enable the SAML Identity Provider to Map Team Membership + +Terraform Enterprise can automatically add users to teams based on their SAML assertion so you can manage team membership in your directory service. + +## Configure Team Membership Mapping + +Enable the **Use SAML to manage team memberships** option on ths site administation page to allow the SAML identity provider to control team membership. + +When you enable it, you must specify the name of a SAML attribute in the [Team Attribute Name](/terraform/enterprise/saml/configuration#attributes) setting, and make sure the AttributeStatement in the SAMLResponse contains a list of AttributeValue items in the correct format. + +When team membership management is enabled, users logging in via SAML are automatically added to the teams included in their assertion, and automatically removed from any teams that _aren't_ included in their assertion. This overrides any manually set team memberships; whenever the user logs in, their team membership is adjusted to match their SAML assertion. + +Any team names that don't match existing teams are ignored; Terraform Enterprise will not automatically create new teams. + +To disable team membership mapping, uncheck the "Use SAML to manage team memberships" checkbox in the SAML admin page. With mapping disabled, Terraform Enterprise won't automatically manage team membership on login, and you can manually add users to teams via the organization's Teams page. + +## Team Names and SSO Team IDs + +Terraform Enterprise expects the team names in the team membership SAML attribute to exactly match its own team names, or its configured SSO Team IDs. This match is case sensitive. + +SSO Team IDs can be configured via the organization's Teams page. If one is configured, Terraform Enterprise will also attempt to match the chosen SAML attribute against the SSO Team ID (in addition to the team name) when mapping users to teams. This is useful if the chosen team membership SAML attribute is not human readable, and is not used as the team's name in Terraform Enterprise. + +Note that team names are unique across an organization but not necessarily unique across a whole Terraform Enterprise instance. If a user is a member of multiple organizations, their SAML assertion might add them to similarly-named teams in each organization. Keep this in mind when naming your teams. + +## Managing Membership of the Owners Team + +Since [the "owners" team](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) is especially important, Terraform Enterprise defaults to NOT managing its membership via SAML. Unless you specifically enable it, Terraform Enterprise won't automatically add or remove any owners, and you can manually manage membership via the teams page. + +You can enable automatic membership in the owners team (on a per-organization basis) by explicitly specifying an alias (role ID) for it. On your organization settings page, click "Teams" and then click the owners team. If SAML is enabled, there will be a "SAML Role ID" field. Enter a legal team name as an ID and click "Save." The ID can be "owners," but it cannot conflict with any other team name. + +Before enabling membership mapping for owners, double-check that your chosen role ID appears in the SAML assertion for users who should be owners. It's worth some extra effort to avoid accidentally removing people from the owners team. + +## Site Admins + +If the "Site Admin Role" setting (in [the SAML settings](/terraform/enterprise/saml/configuration)) is enabled, the selected special team name (default: `site-admins`) will add a user as a [site admin](/terraform/enterprise/application-administration) for the Terraform Enterprise instance. + +-> **Note:** Instead of treating site admins like a team, we recommend using the "Site Admin Attribute Name" setting, which manages admin access via a dedicated SAML attribute. If enabled, this attribute overrides the special site admin team name. + +Site admins can also always log in to Terraform Enterprise directly. If they are disabled on the identity provider but still enabled in Terraform Enterprise and bypass SSO, they will still be able to log in. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/troubleshooting.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/troubleshooting.mdx new file mode 100644 index 0000000000..4edac4f3ab --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/saml/troubleshooting.mdx @@ -0,0 +1,138 @@ +--- +page_title: Troubleshoot SAML SSO integrations for Terraform Enterprise +description: >- + Terraform Enterprise includes debugging functionality to help you troubleshoot SAML SSO issues. Learn how SAML single sign-on troubleshooting tasks. +--- + +# Troubleshoot SAML SSO Integrations + +This topic describes troubleshooting steps for debugging SAML single sign-on integrations for Terraform Enterprise. + +## Requirements + +You must use Terraform Enterprise v201807-2 or later to use debugging functionality. If you would like assistance with upgrading, [contact support](/terraform/enterprise/deploy/troubleshoot/contact-support). + +## Disable SAML Single Sign-On + +Before starting, disable SAML SSO by going to `https:///app/admin/saml` and unchecking the Enable SAML Single Sign-On checkbox. It's best to start from a clean setup. + +## Create a non-SSO admin account for recovery + +Before troubleshooting, create a non-SSO admin account with an email address not associated with your identity provider (such as SAML). + +This non-SSO admin account allows you to log in circumstances where someone accidentally revokes admin access to other SAML-controlled accounts. If your spare non-SSO admin account uses the same email address as your SAML-controlled account, both accounts are affected if your SAML-controlled account loses admin access. + +### Terraform Enterprise UI + +Open `https:///signup/account` to create the account. Make sure to grant admin access to this user and verify they can log in at `https:///`. + +### Rails console + +You can also use Rails commands to create a non-SSO admin account. +You should only use the following commands when you cannot access a Terraform Enterprise instance through the UI due to a lack of a non-SSO recovery admin account. Refer to [Terraform Enterprise UI](#terraform-enterprise-ui) for additional information. +1. Access the Rails console by running the following command to attach to the Terraform Enterprise container: + + + + + ```shell-session + sudo docker exec -ti ptfe_atlas /usr/bin/init.sh /app/scripts/wait-for-token -- bash -ic 'cd /app && bin/rails c' + ``` + + + + + ```shell-session + sudo docker exec -ti tfe-atlas /usr/bin/init.sh /app/scripts/wait-for-token -- bash -ic 'cd /app && bin/rails c' + ``` + + + + +1. Create a user in the Rails console and assign it to a `u` variable: + + ```ruby + u = User.create!(email: "example@email.com", username: "example", password: "example", is_admin: true) + ``` + +1. Confirm the user. If you skip this step, Terraform Enterprise sends a request confirmation email: + + ```ruby + u.confirm + u.save + ``` + +1. Use the Rails console to add the new user to your organization's owners team: + + ```ruby + Organization.find_by_name("your-org").add_owner!(u) + ``` + +1. Log into the Terraform Enterprise instance as the new user and disable or reconfigure SSO to allow general access to the system. + +## Enable SAML SSO and SAML debugging + +### Enable SAML SSO + +Enable SAML SSO by following the [configuration instructions](/terraform/enterprise/saml/configuration). + +### Enable SAML debugging + +Enable SAML debugging by going to `https:///app/admin/saml`. + +![image](/img/docs/saml-sso-enable.png) + +## Test sign-on + +Try signing on by going to `https:///` and clicking the "Log in via SAML" button. Verify the page says `WARNING: SAML debugging is enabled`. + +If login fails, the SAMLResponse XML document sent from the identity provider is shown. The XML document may contain the user's username, list of roles, and other attributes. Checking the format of the email address and username and whether the desired list of roles is included may assist with debugging. + +![image](/img/docs/saml-response.png) + +If there is a configuration error, that is also shown on the login form. + +![image](/img/docs/saml-error.png) + +Fix the configuration error and try to log in again. + +## Common configuration errors + +Most errors will be from misconfiguration and will be shown in the red box on the Terraform Enterprise login form. If you have configured Terraform Enterprise to use an identity provider then be sure to manage users in the identity provider rather than Terraform Enterprise. Specifically, do not suspend identity provider managed users through Terraform Enterprise. + +**CONFIGURATION ERROR: `https:///metadata` is not a valid audience for this Response - Valid audiences: `https:///users/saml/metadata`**
+The audience URL was not configured correctly in the identity provider.
+**How to resolve:** Open the Terraform Enterprise admin settings for SAML SSO, copy the ACS Consumer URL, then paste it into the identity provider settings. + +**CONFIGURATION ERROR: The response was received at `https:///auth` instead of `https:///users/saml/auth`**
+The recipient URL was not configured correctly in the identity provider.
+**How to resolve:** Open the Terraform Enterprise admin settings for SAML SSO, copy the Metadata URL, then paste it into the identity provider settings. + +**CONFIGURATION ERROR: Invalid Signature on SAML Response**
+Incorrect IdP certificate stored on Terraform Enterprise.
+**How to resolve:** Open the Terraform Enterprise admin settings for SAML SSO, and then paste the correct certificate under IDP certificate. + +**ERROR: Validation failed: Email is invalid, Email is not a valid email address, Username has already been taken**
+NameID is invalid. It must be an email address.
+**How to resolve:** Open the identity provider settings and configure email address as the value for NameID. + +**ERROR: Mail::AddressList can not parse |{onelogin:email}|: Only able to parse up to "{onelogin:email}"**
+The NameID that was received was blank.
+**How to resolve:** Open the identity provider settings and configure email address as the value for NameID. + +**ERROR: nested asn1 error**
+The identity provider certificate is invalid or was not pasted correctly into Terraform Enterprise.
+**How to resolve:** Open the identity provider settings, copy the certificate, then paste it into the "IDP Certificate" field in Terraform Enterprise. + +**ERROR: Issuer of assertion not found or multiple**
+Terraform Enterprise was unable to determine the issuer of the SAML response.
+**How to resolve:** The most common reason for this issue is that an F5 load balancer is not signing responses, resulting in the `` and related elements not being present. Follow the steps under **Configuring SAML SP Connectors** on [Using APM as a SAML IdP](https://support.f5.com/kb/en-us/products/big-ip_apm/manuals/product/apm-authentication-single-sign-on-12-1-0/29.html), particularly step 9c. If you are not using an F5 as part of your SAML setup, see below to contact support. + +## Contacting support + +If you're not able to resolve the error using the steps above, [contact out to support](/terraform/enterprise//deploy/troubleshoot/contact-support). When contacting support, please provide: + +- A screenshot of "SAML Response" and "Processed attributes" shown on the login page after failed login. +- A screenshot of the error on the login page. +- The [SAMLResponse XML document](/terraform/enterprise/saml/idp-configuration#example-samlresponse). +- A [support bundle](/terraform/enterprise//deploy/troubleshoot/contact-support). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/2fa.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/2fa.mdx new file mode 100644 index 0000000000..e344aa94df --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/2fa.mdx @@ -0,0 +1,47 @@ +--- +page_title: Configure two-factor authentication +description: Use two-factor authentication to secure access to Terraform Enterprise. +source: terraform-docs-common +--- + +# Configure two-factor authentication + +User accounts can be additionally protected with two-factor authentication (2FA), and an organization owner can make this a requirement for all users. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Setting up Two-factor Authentication + +To reach your user security settings page: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Click the user icon in the upper right corner of the screen. +3. Choose **Account Settings** from the menu. + +Once on this page you can set-up authentication with either a TOTP-compliant application and/or an SMS-enabled phone number. Choose your preferred authentication method and enter a phone number (optional if using an application), then follow the instructions to finish the configuration. If you are using an application, you must scan a QR code to enable it; for either method, you must enter valid authentication codes to verify a successful set-up. + +After you finish, the two-factor authentication settings will change to show your currently configured authentication method. You can click the "Reveal codes" link to view backup codes, or use the "Disable 2FA" button to disable two-factor authentication. + +## Logging in with Two-factor Authentication + +After two-factor authentication has been successfully set-up you will need to enter the code from your TOTP-compliant application or from an SMS sent to your approved SMS-enabled phone number on login. + +If necessary you can also use a backup code by clicking "Use a recovery code". Please remember that each backup code can only be used to log in once. + +## Requiring Two-factor Authentication for All Users + +If you are an organization owner you can require all users within your organization to use two-factor authentication. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Click **Settings** in your organization to reach your organization'a settings page, then click **Authentication**. + +Click the button "Require two-factor". Please remember that all organization owners must have two-factor authentication on before this can be set. + +## Requiring Two-factor Authentication for Users with HashiCorp Cloud Platform + +When you require two-factor authentication for all users and have users who [sign in with their HashiCorp Cloud Platform account](/terraform/enterprise/users-teams-organizations/users#log-in-with-your-hashicorp-cloud-platform-account), the required configuration for each organization member depends on their linked HashiCorp Cloud identity: + +- **Email**: Follow the instructions in the [HashiCorp Cloud MFA](/hcp/docs/hcp/admin/iam/mfa) docs. +- **GitHub**: Follow the instructions in the [Configuring GitHub two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) docs. +- **SSO**: HCP Terraform does not currently support HCP SSO accounts. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/api-tokens.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/api-tokens.mdx new file mode 100644 index 0000000000..54b269b565 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/api-tokens.mdx @@ -0,0 +1,125 @@ +--- +page_title: Manage API tokens for Terraform Enterprise +description: >- + Use API tokens to authenticate with Terraform Enterprise and perform API + operations. +source: terraform-docs-common +--- + +# API Tokens + +This topic describes the distinct types of API tokens you can use to authenticate with HCP Terraform. + +Note that HCP Terraform only displays API tokens once when you initially create them and are obfuscated thereafter. If the token is lost, it must be regenerated. + +Refer to [Team Token API](/terraform/enterprise/api-docs/team-tokens) and [Organization Token API](/terraform/enterprise/api-docs/organization-tokens) for additional information about using the APIs. + +## User API Tokens + +API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/enterprise/users-teams-organizations/users#api-tokens) documentation. + +## Team API Tokens + +API tokens may belong to a specific team. Team API tokens allow access to the workspaces that the team has access to, without being tied to any specific user. + +Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens. + +Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. + +Owners and users with [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permissions have the ability to enable and disable team token management for a team, which limits the actions that team members can take on a team token. Refer to [Allow Member Token Management](/terraform/enterprise/users-teams-organizations/permissions#allow-member-token-management) for more information. + +Team API tokens are designed for performing API operations on workspaces. They have the same access level to the workspaces the team has access to. For example, if a team has permission to apply runs on a workspace, the team's token can create runs and configuration versions for that workspace via the API. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Note that the individual members of a team can usually perform actions the team itself cannot, since users can belong to multiple teams, can belong to multiple organizations, and can authenticate with Terraform's `atlas` backend for running Terraform locally. + +If an API token is generated for the "owners" team, then that API token will have all of the same permissions that an organization owner would. + +## Organization API Tokens + +API tokens may be generated for a specific organization. Organization API tokens allow access to the organization-level settings and resources, without being tied to any specific team or user. + +To manage the API token for an organization, go to **Organization settings > API Token** and use the controls under the "Organization Tokens" header. + +Each organization can have **one** valid API token at a time. Only [organization owners](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) can generate or revoke an organization's token. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Organization API tokens are designed for creating and configuring workspaces and teams. We don't recommend using them as an all-purpose interface to HCP Terraform; their purpose is to do some initial setup before delegating a workspace to a team. For more routine interactions with workspaces, use [team API tokens](#team-api-tokens). + +Organization API tokens have permissions across the entire organization. They can perform all CRUD operations on most resources, but have some limitations; most importantly, they cannot start runs or create configuration versions. Any API endpoints that can't be used with an organization API token include a note like the following: + +-> **Note:** This endpoint cannot be accessed with [organization tokens](#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](#team-api-tokens). + + + +## Audit trail tokens + +You can generate an audit trails token to read an organization's [audit trails](/terraform/enterprise/api-docs/audit-trails). Use this token type to authenticate integrations pulling audit trail data, for example, using the [HCP Terraform for Splunk](/terraform/enterprise/integrations/splunk) app. + +To manage an organization's audit trails token, go to **Organization settings > API Token** and use the settings under the "Audit Token" header. + +Each organization can only have a _single_ valid audit trails token. Only [organization owners](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) can generate or revoke an organization's audit trails token. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + + + +## Agent API Tokens + +[Agent pools](/terraform/cloud-docs/agents) have their own set of API tokens which allow agents to communicate with HCP Terraform, scoped to an organization. These tokens are not valid for direct usage in the HCP Terraform API and are only used by agents. + +## Access Levels + +The following chart illustrates the various access levels for the supported API token types. Some permissions are implicit based on the token type, others are dependent on the permissions of the associated user, team, or organization. + +🔵 = Implicit for token type 🔶 = Requires explicit permission + +| | User tokens | Team tokens | Organization tokens | +| ---------------------------------- | :---------: | :---------: | :-----------------: | +| **Users** | | | | +| Manage account settings | 🔵 | | | +| Manage user tokens | 🔵 | | | +| **Workspaces** | | | | +| Read workspace variables | 🔶 | 🔶 | 🔵 | +| Write workspace variables | 🔶 | 🔶 | 🔵 | +| Plan, apply, upload states | 🔶 | 🔶 | | +| Force cancel runs | 🔶 | 🔶 | | +| Create configuration versions | 🔶 | 🔶 | | +| Create or modify workspaces | 🔶 | 🔶 | 🔵 | +| Remote operations | 🔶 | 🔶 | | +| Manage run triggers | 🔶 | 🔶 | 🔵 | +| Manage notification configurations | 🔶 | 🔶 | | +| Manage run tasks | 🔶 | 🔶 | 🔵 | +| **Teams** | | | | +| Create teams | 🔶 | 🔶 | 🔵 | +| Modify team | 🔶 | 🔶 | 🔵 | +| Read team | 🔶 | 🔶 | 🔵 | +| Manage team tokens | 🔶 | 🔶 | 🔵 | +| Manage team workspace access | 🔶 | 🔶 | 🔵 | +| Manage team membership | 🔶 | 🔶 | 🔵 | +| **Organizations** | | | | +| Create organizations | 🔵 | | | +| Modify organizations | 🔶 | | | +| Manage organization tokens | 🔶 | | | +| View audit trails | | | 🔵 | +| Invite users to organization | 🔶 | 🔶 | 🔵 | +| **Sentinel** | | | | +| Manage Sentinel policies | 🔶 | 🔶 | 🔵 | +| Manage policy sets | 🔶 | 🔶 | 🔵 | +| Override policy checks | 🔶 | 🔶 | | +| **Integrations** | | | | +| Manage VCS connections | 🔶 | 🔶 | 🔵 | +| Manage SSH keys | 🔶 | 🔶 | | +| Manage run tasks | 🔶 | 🔶 | 🔵 | +| **Modules** | | | | +| Manage Terraform modules | 🔶 | 🔵 (owners) | | + +## Token Expiration + +You can create user, team, and organization tokens with an expiration date and time. Once the expiration time has passed, the token is longer treated as valid and may not be used to authenticate to any API. Any API requests made with an expired token will fail. + +HashiCorp recommends setting an expiration on all new authentication tokens. Creating tokens with an expiration date helps reduce the risk of accidentally leaking valid tokens or forgetting to delete tokens meant for a delegated use once their intended purpose is complete. + +You can not modify the expiration of a token once you have created it. The HCP Terraform UI displays tokens relative to the current user's timezone, but all tokens are passed and displayed in UTC in ISO 8601 format through the HCP Terraform API. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/index.mdx new file mode 100644 index 0000000000..60d193bf5e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/index.mdx @@ -0,0 +1,337 @@ +--- +page_title: Organizations overview +description: >- + Organizations are groups of projects and workspaces that let teams + collaborate. Learn how to create and manage Terraform Enterprise + organizations. +source: terraform-docs-common +--- + +[teams]: /terraform/enterprise/users-teams-organizations/teams + +[users]: /terraform/enterprise/users-teams-organizations/users + +[owners]: /terraform/enterprise/users-teams-organizations/teams#the-owners-team + +# Organizations overview + +This topic provides overview information about how to create and manage organizations in HCP Terraform and Terraform Enterprise. An organization contains one or more projects. + +## Requirements + +The **admin** permission preset must be enabled on your profile to create and manage organizations in the HCP Terraform UI. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for additional information. + +## API and Terraform Enterprise Provider + +In addition to the HCP Terraform UI, you can use the following methods to manage organizations: + +- [Organizations API](/terraform/enterprise/api-docs/organizations) +- The `tfe` provider [`tfe_organization`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/organization) resource + +## Select an organization + +HCP Terraform displays your current organization in the sidebar. To select an organization: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Click the current organization name to view a list of all the organizations where you are a member. +3. Click an organization to select it. HCP Terraform displays list of workspaces within that organization. + +## Join an organization + +To join an organization, the organization [owners][] or a user with specific [team management](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions) permissions must invite you, and you must accept the emailed invitation. [Learn more](#users). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Leave an organization + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and click the Terraform logo in the page header to navigate to the **Organizations** page. +2. Open the **...** ellipses menu next to the organization and select **Leave organization**. + +You do not need permission from the owners to leave an organization, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or [delete the organization](/terraform/enterprise/users-teams-organizations/organizations#general). + +## Create an organization + + + +On Terraform Enterprise, administrators can restrict your ability to create organizations. Refer to [Organization Creation](/terraform/enterprise/admin/application/general#organization-creation) for details. + + + +On HCP Terraform, any user can create a new organization. If you do not belong to any organizations, HCP Terraform prompts you to create one the first time you [sign in](https://app.terraform.io/). To create an organization: + +1. Click the current organization name and select **Create new organization**. The **Create a new organization** page appears. +2. Enter a unique **Organization name** Organization names can include numbers, letters, underscores (`_`), and hyphens (`-`). +3. Provide an **Email address** to receive notifications about the organization. +4. Click **Create organization**. + +HCP Terraform shows the new organization and prompts you to create a new workspace. You can also [invite other users](#users) to join the organization. + + + +## Managed resources + +Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces. + +HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. Each [resource](/terraform/language/resources/syntax) instance in the state equals one managed resource. HCP Terraform includes resources in modules and each resource created with the `count` or `for_each` meta-arguments. HCP Terraform does not include [data sources](/terraform/language/data-sources) in the count. Refer to [Managed Resources Count](/terraform/enterprise/workspaces/state#managed-resources-count) in the workspace state documentation for more details. + +You can view your organization's managed resource count on the **Usage** page. + + + +## Create and manage reserved tag keys + + +You can define reserved tag keys that appear as suggested labels when managers want to add tags to their projects and workspaces in the organization. Refer to [Create and manage reserved tag keys](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for instructions. + +You can also view single-value tags that may already be attached to projects and workspaces. Refer to [Tags](#tags) in the organization settings reference for additional information. + +## Managing settings + +To view and manage an organization's settings, click **Settings**. + +The contents of the organization settings depends on your permissions within the organization. All users can review the organization's contact email, view the membership of any teams they belong to, and view the organization's authentication policy. [Organization owners][owners] can view and manage the entire list of organization settings. Refer to [Organization Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for details. + +You may be able to manage the following organization settings. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Organization settings + +#### General + +Review the organization name and contact email. Organization owners can choose to change the organization name, contact email, and the default execution mode, or delete the organization. When an organization owner updates the default execution mode, all workspaces configured to [inherit this value](/terraform/enterprise/workspaces/settings#execution-mode) will be affected. + +Organization owners can also choose whether [workspace administrators](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) can delete workspaces that are managing resources. Deleting a workspace with resources under management introduces risk because Terraform can no longer track or manage the infrastructure. The workspace's users must manually delete any remaining resources or [import](/terraform/cli/commands/import) them into another Terraform workspace. + + + +Organization owners using HCP Terraform Plus edition can choose whether members with [module management permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) can [generate module tests](/terraform/enterprise/registry/test#generated-module-tests). + + + +##### Renaming an organization + +!> **Warning:** Deleting or renaming an organization can be very disruptive. We strongly recommend against deleting or renaming organizations with active members. + +To rename an organization that manages infrastructure: + +1. Alert all members of the organization about the name change. +2. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to rename. +3. Cancel in progress and pending runs or wait for them to finish. HCP Terraform cannot change the name of an organization with runs in progress. +4. Lock all workspaces to ensure that no new runs will start before you change the name. +5. Rename the organization. +6. Update all components using the HCP Terraform API to the new organization name. This includes Terraform's `cloud` block CLI integration, the `tfe` Terraform provider, and any external API integrations. +7. Unlock workspaces and resume normal operations. + +#### Plan & Billing + +Review the organization's plan and any invoices for previous plan payments. Organization owners can also upgrade to one of HCP Terraform's paid plans, downgrade to a free plan, or begin a free trial of paid features. + +#### Tags + +Click the **Tags** tab in the **Tags Management** screen to view single-value tags that may have already been created in your system. The table on lists the tags in the system, the number of times a tag appears in a project or workspace, and the date the tag was created. + +The only action you can perform in the UI is deleting single-value tags from the system. You can use the following methods to delete single-value tags: + +1. Select one or more tags and click **Delete tags**. +2. Select the **Name** header to select all tags, then click **Delete tags**. +3. Click the trash icon for a tag and confirm that you want to permanently delete it when prompted. + +#### Teams + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +All users in an organization can access the **Teams** page, which displays a list of [teams][] within the organization. + +Organization owners and users with the [include secret teams permission](/terraform/enterprise/users-teams-organizations/permissions#include-secret-teams) can: + +- view all [secret teams](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) +- view each team's membership +- manage team API tokens + +HCP Terraform restricts team creation, team deletion, and management of team API tokens to organization owners and users with the [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permission. Organization owners and users with the [manage membership](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permission can manage team membership. Remember that users must accept their organization invitations before you can add them to a team. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Users + +Organization owners and users with [manage membership](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permissions can invite HCP Terraform users into the organization, cancel invitations, and remove existing members. + +The list of users is separated into one tab for active users and one tab for invited users who have not yet accepted their invitations. For active users, the list includes usernames, email addresses, avatar icons, two-factor authentication status, and current team memberships. Use the **Search by username or email** field to filter these lists. + +User invitations are always sent by email; you cannot invite someone using their HCP Terraform username. To invite a user to an organization: + +1. Click **Invite a user**. The **invite a user** box appears. +2. Enter the user's email address and optionally add them to one or more teams. If the user accepts the invitation, HCP Terraform automatically adds them to the specified teams. + +All permissions in HCP Terraform are managed through teams. Users can join an organization without belonging to any teams, but they cannot use HCP Terraform features until they belong to a team. Refer to [permissions](/terraform/enterprise/users-teams-organizations/permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Variable Sets + +View all of the available variable sets and their variables. Users with [**Manage variable set** permissions](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) can create variable sets and assign them to one or more projects or workspaces. + +Variable sets let you reuse the same variables across multiple workspaces or projects in an organization. For example, you could define a variable set of provider credentials and automatically apply it to several projects or workspaces, rather than manually defining credential variables in each. Changes to variable sets instantly apply to all appropriate workspaces, saving time and reducing errors from manual updates. + +Refer to the [variables overview](/terraform/enterprise/workspaces/variables) documentation for details about variable types, scope, and precedence. Refer to [managing variables](/terraform/enterprise/workspaces/variables/managing-variables) for details about how to create and manage variable sets. + +#### Health + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations: + +- Drift detection determines whether your real-world infrastructure matches your Terraform configuration. Drift detection requires Terraform version 0.15.4+. +- Continuous validation determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. Continuous validation requires Terraform version 1.3.0+. + +You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings. Refer to [Health](/terraform/enterprise/workspaces/health) in the workspaces documentation for more details. + +#### Runs + +From the Workspaces page, click **Settings** in the sidebar, then **Runs** to view all of the current runs in your organization's workspaces. The **Runs** page displays: + +- The name of the run +- The run's ID +- What triggered the run +- The workspace and project where the run is taking place +- When the latest change in the run occurred +- A button allowing you to cancel that run + +You can apply the following filters to limit the runs HCP Terraform displays: + +- Click **Needs Attention** to display runs that require user input to continue, such as approving a plan or overriding a policy. +- Click **Running** to display runs that are in progress. +- Click **On Hold** to display paused runs. + +For precise filtering, click **More filters** and check the boxes to filter runs by specific [run statuses](/terraform/enterprise/run/states), [run operations](/terraform/enterprise/run/modes-and-options), workspaces, or [agent pools](/terraform/cloud-docs/agents/agent-pools). Click **Apply filters** to list the runs that match your criteria. + +You can dismiss any of your filtering criteria by clicking the **X** next to the filter name above the table displaying your runs. + +For more details about run states, refer to [Run States and Stages](/terraform/enterprise/run/states). + +### Integrations + +#### Cost Estimation + +Enable and disable the [cost estimation](/terraform/enterprise/cost-estimation) feature for all workspaces. + +#### Policies + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policies let you define and enforce rules for Terraform runs. You can write them using either the [Sentinel](/terraform/enterprise/policy-enforcement/sentinel) or [Open Policy Agent (OPA)](/terraform/enterprise/policy-enforcement/opa) policy-as-code frameworks and then group them into policy sets that you can apply to workspaces in your organization. To create policies and policy sets, you must have [permission to manage policies](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions). + +#### Policy Sets + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Create groups of policies and enforce those policy sets globally or on specific [projects](/terraform/enterprise/projects/manage) and workspaces. You can create policy sets through the Terraform API, by connecting a VCS repository containing policies, or directly in HCP Terraform. To create policies and policy sets, you must have [permission to manage policies](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions). + +Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Run Tasks + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +Manage the run tasks that you can add to workspaces within the organization. [Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) let you integrate third-party tools and services at specific stages in the HCP Terraform run lifecycle. + +### Security + +#### Agents + + + +@include 'tfc-package-callouts/agents.mdx' + + + +Create and manage [HCP Terraform agent pools](/terraform/cloud-docs/agents). HCP Terraform agents let HCP Terraform communicate with isolated, private, or on-premises infrastructure. This is useful for on-premises infrastructure types such as vSphere, Nutanix, OpenStack, enterprise networking providers, and infrastructure within a protected enclave. + +#### API Tokens + +Organization owners can set up a special [Organization API Token](/terraform/enterprise/users-teams-organizations/api-tokens) that is not associated with a specific user or team. + +#### Authentication + +Organization owners can determine when users must reauthenticate and require [two-factor authentication](/terraform/enterprise/users-teams-organizations/2fa) for all members of the organization. + +#### SSH Keys + +Manage [SSH keys for cloning Git-based modules](/terraform/enterprise/workspaces/settings/ssh-keys) during Terraform runs. This does not include keys to access a connected VCS provider. + +#### SSO + +Organization owners can set up an SSO provider for the organization. + +### Version Control + +#### VCS General + +Configure [Automatically cancel plan-only runs triggered by outdated commits](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management) to manage the setting. + +#### VCS Events + +-> **Note:** This feature is in beta. + +Review the event logs for GitLab.com connections. + +#### VCS Providers + +Configure [VCS providers](/terraform/enterprise/vcs) to use in the organization. You must have [permission to manage VCS settings](/terraform/enterprise/users-teams-organizations/permissions). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Destruction and Deletion + +#### Data Retention Policies + + +Data retention policies are exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +An organization owner can set or override the following data retention policies: + +- **Admin default policy** +- **Do not auto-delete** +- **Auto-delete data** + +Setting the data retention policy to **Admin default policy** disables the other data retention policy settings. + +By default, the **Do not auto-delete** option is enabled for an organization. This option directs Terraform Enterprise to retain data associated with configuration and state versions, but organization owners can define configurable data retention policies that allow Terraform to _soft delete_ the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform can delete the object after a set number of days. + +Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection process begins, you can restore soft deleted objects using the APIs described in the [configuration version documentation](/terraform/enterprise/api-docs/configuration-versions) and the [state version documentation](/terraform/enterprise/api-docs/state-versions). Terraform permanently deletes the archivist storage after the garbage collection grace period elapses. + +The organization policy is the default policy applied to all workspaces, but members of individual workspaces can set overriding policies for their workspaces that take precedence over the organization policy. + +## Trial Expired Organizations + +HCP Terraform paid features are available as a free trial. When a free trial has expired, the organization displays a banner reading **TRIAL EXPIRED — Upgrade Required**. + +Organizations with expired trials return to the feature set of a free organization, but they retain any data created as part of paid features. Specifically, HCP Terraform disables the following features: + +- Teams other than `owners` and locks users who do not belong to the `owners` team out of the organization. HCP Terraform preserves team membership and permissions and re-enables them after you upgrade the organization. +- Sentinel policy checks. HCP Terraform preserves existing policies and policy sets and re-enables them after you upgrade the organization. +- Cost estimation. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/manage-reserved-tags.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/manage-reserved-tags.mdx new file mode 100644 index 0000000000..60709f95c5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/manage-reserved-tags.mdx @@ -0,0 +1,59 @@ +--- +page_title: Create and manage reserved tag keys +description: >- + Reserved tag keys let you organize projects and workspaces and track + consumption. Learn how to create and manage reserved tag keys. +source: terraform-docs-common +--- + +# Create and manage reserved tag keys + +This topic describes how to create and manage reserved tag keys in HCP Terraform. You can use reserved tag keys to help managers consistently label workspaces and projects in your organization. + +## Introduction + +You can define reserved tag keys that appear as suggested labels when managers want to add tags to their projects and workspaces in the organization. Doing so helps you standardize tag keys and prevent duplicates that affect your ability to track resources. + +Refer to the following topics for information about creating and managing tags attached to projects and workspaces: + +- [Create a project](/terraform/enterprise/projects/manage#create-a-project) +- [Create workspace tags](/terraform/enterprise/workspaces/tags) + +## Requirements + +The **admin** permission preset must be enabled on your profile to create and manage reserved tags. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for additional information. + +## Define a reserved tag key + +You can define reserved tag keys for your organization so that project and workspace managers can use consistent labels. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to define a reserved tag for. +2. Choose **Settings** from the sidebar, then **Tags**. +3. Click on the **Reserved Keys** tab. +4. Click **New reserved tag key** and specify a key value when prompted. Keys are unique and can have up to 128 characters. You can use letters, numbers, spaces, and the following special characters: `.`, `=`, `+`, `-`, `@`, `:`, `-`, and `_`. +5. You can enable the **Disable overrides** option to prevent project and workspace managers from overriding the key. Refer to [Disable overrides for project tags](#disable-overrides-for-project-tags) for additional information. +6. Click **Save** to finish adding the key. + +## Delete a reserved key + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to delete a reserved tag. +2. Choose **Settings** from the sidebar, then **Tags**. +3. Click on the **Reserved Keys** tab. +4. Open the ellipses menu and choose **Delete <key-name>**. +5. Click **Yes, delete reserved key** when prompted. + +To re-add a key, you must manually complete the steps described in [Define a reserved tag key](#define-a-reserved-tag-key). + +## Edit a reserved key + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to edit a reserved tag. +2. Choose **Settings** from the sidebar, then **Tags**. +3. Click on the **Reserved Keys** tab. +4. Open the ellipses menu and choose **Edit <key-name>**. +5. Specify your changes and click **Save**. + +## Disable overrides for project tags + +Enable the **Disable overrides** option when creating or editing a reserved tag key to prevent project and workspace managers from overriding the tag keys. + +This option is not retroactive. When a workspace contains keys that were overridden before you enabled the **Disable overrides** option, you must first remove the tags from the workspace. You can then re-apply the keys to the workspace so that HCP Terraform can allow future updates to the workspace tag bindings. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management.mdx new file mode 100644 index 0000000000..8945635223 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management.mdx @@ -0,0 +1,45 @@ +--- +page_title: Automatically cancel plan-only runs triggered by outdated commits +description: >- + Learn how to configure Terraform Enterprise to automatically cancel Terraform + plan operations triggered by pull requests when new commits are pushed to the + VCS. +source: terraform-docs-common +--- + +# Automatically cancel plan-only runs + +This topic describes how to configure HCP Terraform to automatically cancel plan-only Terraform run triggered by pull requests in the VCS. + +## Introduction + +When connected to a VCS, HCP Terraform can automatically start a Terraform run that performs a `terraform plan` operation when someone creates a pull request (PR) in the repository. Refer to [Connecting to VCS](/terraform/enterprise/vcs) for additional information. + +When team members push new commits to the same branch, HCP Terraform starts new run that performs a `terraform plan` operation. But as team members push new commits, the queue of Terraform runs can cause delays and reduce efficiency. + +You can enable the **Automatically cancel speculative plans for outdated commits** option in the organization's settings screen so that HCP Terraform automatically cancel unfinished plan-only runs in VCS workflows. + +## Configure automatic cancellation + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select your organization. +2. Choose **Settings** from the sidebar. +3. Under the **Version Control** group of settings, click **General**. +4. Enable the **Automatically cancel speculative plans for outdated commits** option under the **Manage speculative plans** section. +5. Click **Update settings**. + +After enabling the option, HCP Terraform cancels ongoing or pending speculative plans when new commits are received on the same branch. + +## Automated cancellation notifications + +When the **Automatically cancel speculative plans for outdated commits** option is enabled, HCP Terraform notifies you about plan-only runs that are canceled as a result of the setting. Notifications appear in the following screens: + +- **Run details page**. Refer to [Viewing and Managing Runs](/terraform/enterprise/run/manage) for additional information. + +- **VCS status checks**. When the **Non-aggregated status checks** option is enabled in the version control settings, the notification explicitly states when a plan has been canceled automatically. + + When the **Aggregated status checks** option is enabled, HCP Terraform includes canceled plans in the result and identifies them separately from manually canceled plans. + + Refer to [VCS Status Checks](/terraform/enterprise/users-teams-organizations/organizations/vcs-status-checks) for additional information. + + +- **Aggregated status page**. HCP Terraform prints the cancellation message in the aggregated status page in the **Resources to be changed** section. The section may not reflect a complete result if all runs associated with the commit reach completion. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/vcs-status-checks.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/vcs-status-checks.mdx new file mode 100644 index 0000000000..4b1983ef17 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/organizations/vcs-status-checks.mdx @@ -0,0 +1,49 @@ +--- +page_title: Configure VCS status checks +description: >- + VCS status checks send notifications to your version control provider. Learn + how to configure VCS status checks in Terraform Enterprise. +source: terraform-docs-common +--- + +# Configure VCS status checks + +Status checks are notifications sent to your version control system's VCS provider, providing details about specific commits, including the present status of the HCP Terraform run. Please refer to your VCS provider's documentation regarding status checks (e.g., [GitHub Status Checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks)). + +## Permissions + +To modify VCS Status Checks settings, you must have [Manage VCS Settings](/terraform/enterprise/users-teams-organizations/permissions#manage-vcs-settings) permissions. + +## Managing organization VCS status check settings + +Organization owners can choose between _aggregated_ (default) and _non-aggregated_ status checks. This setting determines whether detailed information and links are accessed directly from the VCS provider or HCP Terraform. + +This setting also determines the number of status checks directly sent to the VCS Provider in response to actions such as pull or merge requests. + +To view and manage an organization’s VCS Status Check settings, click **Settings** then **Version Control**. + +### Aggregated status checks + +Aggregated status checks offer a streamlined experience if you have a single repository containing configuration for many workspaces (a.k.a., a monorepo). + +When aggregated status checks are enabled, HCP Terraform sends one VCS status check for all runs triggered by a VCS event. If multiple workspaces rely on a shared repository, HCP Terraform aggregates the status checks for these workspaces into one summary. This summary is unique to the workspace's organization and VCS client connection. + +You can access additional information about an aggregated status check in HCP Terraform by clicking the **Details** link a status check provides. This link directs you to an HCP Terraform page that offers the consolidated status check results across multiple workspaces, highlighting details such as resource changes and issues that require attention. + +![Screenshot: Organization Aggregated status checks](/img/docs/organization-vcs-general-aggregated-status-checks.png) + +### Non-aggregated status checks + +Non-aggregated status checks send your VCS provider a status check for each triggered workspace and related run stage in response to a VCS event. For example, a VCS push triggers checks for each related workspace's run stages, including the plan operation, policy checks, cost estimation, run tasks, and more. + +If you have a manageable amount of workspaces and want to visualize status checks on your VCS Provider rather than in HCP Terraform, use non-aggregated status checks. + +![Screenshot: Organization Non-aggregated status checks](/img/docs/organization-vcs-general-non-aggregated-status-checks.png) + +#### Send passing commit statuses + +-> **Note:** Organization owners can only enable the **Send passing commit statuses** setting if the **Aggregated status checks** setting is disabled. + +Workspaces that use part of a shared repository do not typically run plans for changes that do not affect their files. This includes [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans) on pull requests. Since **pending** VCS status checks can block pull requests, workspaces automatically send passing commit statuses for any PRs that do not affect their files. + +You can disable this behavior if it creates too many status checks for your VCS provider. You may want to do this if you have a large number of workspaces sharing one VCS repository. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/permissions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/permissions.mdx new file mode 100644 index 0000000000..26e3e065f2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/permissions.mdx @@ -0,0 +1,392 @@ +--- +page_title: Permission model in Terraform Enterprise +description: >- + Use the Terraform Enterprise permission model to manage user access to + organizations, projects, and workspaces. +source: terraform-docs-common +--- + +# Permission model + + + +-> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). + + + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +> **Hands-on:** Try the [Manage Permissions in HCP Terraform](/terraform/tutorials/cloud/cloud-permissions?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. + +HCP Terraform's access model is team-based. In order to perform an action within an HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. + +The permissions model is split into organization-level, project-level, and workspace-level permissions. Additionally, every organization has a special team named "owners", whose members have maximal permissions within the organization. + +## Organization Owners + +Every organization has a special "owners" team. Members of this team are often referred to as "organization owners". + +Organization owners have every available permission within the organization. This includes all organization-level permissions, and the highest level of workspace permissions on every workspace. + +There are also some actions within an organization that are only available to owners. These are generally actions that affect the permissions and membership of other teams, or are otherwise fundamental to the organization's security and integrity. + +Permissions for the owners team include: + +- Manage workspaces (refer to [Organization Permissions][] below; equivalent to admin permissions on every workspace) +- Manage projects (refer to [Organization Permissions][] below; equivalent to admin permissions on every project and workspace) +- Manage policies (refer to [Organization Permissions][] below) +- Manage policy overrides (refer to [Organization Permissions][] below) +- Manage VCS settings (refer to [Organization Permissions][] below) +- Manage the private registry (refer to [Organization Permissions][] below) +- Manage Membership (refer to [Organization Permissions][] below; invite or remove users from the organization itself, and manage the membership of its teams) +- View all secret teams (refer to [Organization Permissions][] below) +- Manage agents (refer to [Organization Permissions][] below) +- Manage organization permissions (refer to [Organization Permissions][] below) +- Manage all organization settings (owners only) +- Manage organization billing (owners only, not applicable to Terraform Enterprise) +- Delete organization (owners only) + +This list is not necessarily exhaustive. + +[Organization Permissions]: #organization-permissions + +## Workspace Permissions + +[workspace]: /terraform/enterprise/workspaces + +Most of HCP Terraform's permissions system is focused on workspaces. In general, administrators want to delegate access to specific collections of infrastructure; HCP Terraform implements this by granting permissions to teams on a per-workspace basis. + +There are two ways to choose which permissions a given team has on a workspace: fixed permission sets, and custom permissions. Additionally, there is a special "admin" permission set that grants the highest level of permissions on a workspace. + +### Implied Permissions + +Some permissions imply other permissions; for example, the run access plan permission also grants permission to read runs. + +If documentation or UI text states that an action requires a specific permission, it is also available for any permission that implies that permission. + +### General Workspace Permissions + +[General Workspace Permissions]: #general-workspace-permissions + +The following workspace permissions can be granted to teams on a per-workspace basis. They can be granted via either fixed permission sets or custom workspace permissions. + +-> **Note:** Throughout the documentation, we refer to the specific permission an action requires (like "requires permission to apply runs") rather than the fixed permission set that includes that permission (like "requires write access"). + +- **Run access:** + - **Read:** — Allows users to view information about remote Terraform runs, including the run history, the status of runs, the log output of each stage of a run (plan, apply, cost estimation, policy check), and configuration versions associated with a run. + - **Plan:** — _Implies permission to read._ Allows users to queue Terraform plans in a workspace, including both speculative plans and normal plans. Normal plans must be approved by a user with permission to apply runs. This also allows users to comment on runs. + - **Apply:** — _Implies permission to plan._ Allows users to approve and apply Terraform plans, causing changes to real infrastructure. +- **Variable access:** + - **No access:** — No access is granted to the values of Terraform variables and environment variables for the workspace. + - **Read:** — Allows users to view the values of Terraform variables and environment variables for the workspace. Note that variables marked as sensitive are write-only, and can't be viewed by any user. + - **Read and write:** — _Implies permission to read._ Allows users to edit the values of variables in the workspace. +- **State access:** + + - **No access:** — No access is granted to the state file from the workspace. + - **Read outputs only:** — Allows users to access values in the workspace's most recent Terraform state that have been explicitly marked as public outputs. Output values are often used as an interface between separate workspaces that manage loosely coupled collections of infrastructure, so their contents can be relevant to people who have no direct responsibility for the managed infrastructure but still indirectly use some of its functions. This permission is required to access the [State Version Outputs](/terraform/enterprise/api-docs/state-version-outputs) API endpoint. + + -> **Note:** **Read state versions** permission is required to use the `terraform output` command or the `terraform_remote_state` data source against the workspace. + - **Read:** — _Implies permission to read outputs only._ Allows users to read complete state files from the workspace. State files are useful for identifying infrastructure changes over time, but often contain sensitive information. + - **Read and write:** — _Implies permission to read._ Allows users to directly create new state versions in the workspace. Applying a remote Terraform run creates new state versions without this permission, but if the workspace's execution mode is set to "local", this permission is required for performing local runs. This permission is also required to use any of the Terraform CLI's state manipulation and maintenance commands against this workspace, including `terraform import`, `terraform taint`, and the various `terraform state` subcommands. +- **Other controls:** + - **Download Sentinel mocks:** — Allows users to download data from runs in the workspace in a format that can be used for developing Sentinel policies. This run data is very detailed, and often contains unredacted sensitive information. + - **Manage Workspace Run Tasks:** — Allows users to associate or dissociate run tasks with the workspace. HCP Terraform creates Run Tasks at the organization level, where you can manually associate or dissociate them with specific workspaces. + - **Lock/unlock workspace:** — Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to "local", users must have this permission to perform local CLI runs using the workspace's state. + +### Fixed Permission Sets + +Fixed permission sets are bundles of specific permissions for workspaces, which you can use to delegate access to workspaces easily. + +Each permissions set targets a level of authority and responsibility for a given workspace's infrastructure. A permission set can grant permissions that recipients do not require but offer a balance of simplicity and utility. + +#### Workspace Admins + +Much like the owners team has full control over an organization, each workspace has a special "admin" permissions level that grants full control over the workspace. Members of a team with admin permissions on a workspace are sometimes called "workspace admins" for that workspace. + +Admin permissions include the highest level of general permissions for the workspace. There are also some permissions that are only available to workspace admins, which generally involve changing the workspace's settings or setting access levels for other teams. + +Workspace admins have all [General Workspace Permissions](#general-workspace-permissions), as well as the ability to do the following tasks: + +- Read and write workspace settings. This includes general settings, notification configurations, run triggers, and more. +- Set or remove workspace permissions for visible teams. Workspace admins cannot view or manage teams with the [**Secret**](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) visibility option enabled unless they are also organization owners. +- Delete the workspace + - Depending on the [organization's settings](/terraform/enterprise/users-teams-organizations/organizations#general), workspace admins may only be able to delete the workspace if it is not actively managing infrastructure. Refer to [Deleting a Workspace With Resources Under Management](/terraform/enterprise/workspaces/settings#deleting-a-workspace-with-resources-under-management) for details. + +#### Write + +The "write" permission set is for people who do most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following workspace permissions: + +- Run access - Apply +- Variable access - Read and write +- State access - Read and write +- Other access - Lock/unlock workspace +- Other access - Download Sentinel mocks + +See [General Workspace Permissions][] above for details about specific permissions. + +#### Plan + +The "plan" permission set is for people who might propose changes to managed infrastructure, but whose proposed changes should be approved before they are applied. Plan access grants the following workspace permissions: + +- Run access - Plan +- Variable access - Read +- State access - Read + +See [General Workspace Permissions][] above for details about specific permissions. + +#### Read + +The "read" permission set is for people who need to view information about the status and configuration of managed infrastructure in order to do their jobs, but aren't responsible for maintaining that infrastructure. Read access grants the following workspace permissions: + +- Run access - Read +- Variable access - Read +- State access - Read + +See [General Workspace Permissions][] above for details about specific permissions. + +### Custom Workspace Permissions + +Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. This enables more task-focused permission sets and tighter control of sensitive information. + +You can use custom permissions to assign any of the permissions listed above under [General Workspace Permissions][], with the exception of admin-only permissions. + +The minimum custom permissions set for a workspace is the permission to read runs; the only way to grant a team lower access is to not add them to the workspace at all. + +Some permissions - such as the runs permission - are tiered: you can assign one permission per category, since higher permissions include all of the capabilities of the lower ones. + +## Project Permissions + +You can assign project-specific permissions to teams. + +### Implied Permissions + +Some permissions imply other permissions. For example, permission to update a project also grants permission to read a project. + +If an action states that it requires a specific permission level, you can perform that action if your permissions _imply_ the stated permission level. + +### General Project Permissions + +[General Project Permissions]: #general-project-permissions + +You can grant the following project permissions to teams on a per-project basis. You can grant these with either fixed permission sets or custom project permissions. + +-> **Note:** Throughout the documentation, we refer to the specific permission an action requires (like "requires permission to apply runs") rather than the fixed permission set that includes that permission (like "requires write access"). + +- **Project access:** + - **Read:** — Allows users to view information about the project including the name. + - **Update:** — _Implies permission to read._ Allows users to update the project name. + - **Delete:** — _Implies permission to update._ Allows users to delete the project. + - **Create Workspaces:** — Allow users to create workspaces in the project. This grants read access to all workspaces in the project. + - **Delete Workspaces:** — Allows users to delete workspaces in the project. + - Depending on the [organization's settings](/terraform/enterprise/users-teams-organizations/organizations#general), workspace admins may only be able to delete the workspace if it is not actively managing infrastructure. Refer to [Deleting a Workspace With Resources Under Management](/terraform/enterprise/workspaces/settings#deleting-a-workspace-with-resources-under-management) for details. + - **Move Workspaces:** — Allows users to move workspaces out of the project. A user _must_ have this permission on both the source _and_ destination project to successfully move a workspace from one project to another. +- **Team management:** + - **None:** — No access to view teams assigned to the project. + - **Read:** — Allows users to see teams assigned to the project for visible teams. + - **Manage:** — _Implies permission to read._ Allows users to set or remove project permissions for visible teams. Project admins can not view or manage [secret teams](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) unless they are also organization owners. +- **Variable sets:** + - **None:** — No access to variable sets owned by the project. However, users with Variable access permissions can view variable sets applied to this project and its workspaces. + - **Read:** — Allows users to view variable sets owned by this project. + - **Manage:** — _Implies permission to read._ Allows users to create, update, and delete variable sets owned by the project. + +See [General Workspace Permissions](#general-workspace-permissions)for the complete list of available permissions for a project's workspaces. + +### Fixed Permission Sets + +Fixed permission sets are bundles of specific permissions for projects, which you can use to delegate access to a project's workspaces easily. + +#### Project Admin + +Each project has an "admin" permissions level that grants permissions for both the project and the workspaces that belong to that project. Members with admin permissions on a project are dubbed that project's "project admins". + +Members of teams with "admin" permissions for a project have [General Workspace Permissions](#general-workspace-permissions) for every workspace in the project, and the ability to: + +- Read and update project settings. +- Delete the project. +- Create workspaces in the project. +- Move workspaces into or out of the project. This also requires project admin permissions for the source or destination project. +- Grant or revoke project permissions for visible teams. Project admins **cannot** view or manage access for teams that are are [Secret](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility), unless those admins are also organization owners. + +#### Maintain + +The "maintain" permission is for people who need to manage existing infrastructure in a single project, while also granting the ability to create new workspaces in that project. Maintain access grants full control of everything in the project, including the following permissions: + +- Admin access for all workspaces in this project. +- Create workspaces in this project. +- Read the project name. +- Lock and unlock all workspaces in this project. +- Read and write variables for all workspaces in this project. +- Access state for all workspaces in this project. +- Approve runs for all workspaces in this project. + +#### Write + +The "write" permission set is for people who do most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following workspace permissions: + +- Read the project name. +- Lock and unlock all workspaces in this project. +- Read and write variables for all workspaces in this project. +- Access state for all workspaces in this project. +- Approve runs for all workspaces in this project. + +#### Read + +The "read" permission set is for people who need to view information about the status and configuration of managed infrastructure for their job function, but are not responsible for maintaining that infrastructure. Read access grants the permissions to: + +- Read the project name. +- Read the workspaces in the project. + +### Custom Project Permissions + +Custom permissions enable you to assign specific and granular permissions to a team. You can use custom permission sets to create task-focused permission sets and control sensitive information. + +You can create a set of custom permissions using any of the permissions listed under [General Project Permissions](#general-project-permissions). + +Some permissions, such as the project access permission, are tiered. You can only assign one permission per category because higher-level permissions include the capabilities of lower levels. + +## Organization Permissions + +Separate from project and workspace permissions, you can grant teams permissions to manage or view certain resources or settings across an organization. To set these permissions for a team, go to your organization's **Settings**. Then click **Teams**, and select the team name from the list. + +The following organization permissions are available: + +### Project permissions + +You must select a level of access for projects. + +#### None + +Members do not have access to projects or workspaces. You can grant permissions to individual projects or workspaces through [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) or [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). + +#### View all projects + +Members can view all projects within the organization. This lets users: + +- View project names in a given organization. + +#### Manage all projects + +Members can create and manage all projects and workspaces within the organization. In addition to the permissions granted by [“Manage all workspaces”](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces), this also lets users: + +- Manage other teams' access to all projects. +- Create, edit, and delete projects (otherwise only available to organization owners). +- Move workspaces between projects. + +### Workspace permissions + +You must select a level of access for workspaces. + +#### None + +Members do not have access to projects or workspaces. You can grant permissions to individual projects or workspaces through [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) or [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). + +#### View all workspaces + +Members can view all workspaces within the organization. This lets users: + +- View information and features relevant to each workspaces (e.g. runs, state versions, variables). + +#### Manage all workspaces + +Members can create and manage all workspaces within the organization. This lets users: + +- Perform any action that requires admin permissions in those workspaces. +- Create new workspaces within the organization's **Default Project**, an action that is otherwise only available to organization owners. +- Create, update, and delete [Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +### Manage Policies + +Allows members to create, edit, read, list and delete the organization's Sentinel policies. + +This permission implicitly gives permission to read runs on all workspaces, which is necessary to set enforcement of [policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets). + +### Manage Run Tasks + +Allows members to create, edit, and delete run tasks on the organization. + +### Manage Policy Overrides + +Allows members to override soft-mandatory policy checks. + +This permission implicitly gives permission to read runs on all workspaces, which is necessary to override policy checks. + +### Manage VCS Settings + +Allows members to manage the set of [VCS providers](/terraform/enterprise/vcs) and [SSH keys](/terraform/enterprise/vcs#ssh-keys) available within the organization. + +### Manage Agent Pools + +Allows members to create, edit, and delete agent pools within their organization. + +This permission implicitly grants access to read all workspaces, which is necessary for agent pool management. + +### Manage Private Registry + +Allows members to publish and delete providers, modules, or both providers and modules in the organization's [private registry](/terraform/enterprise/registry). These permissions are otherwise only available to organization owners. + +### Team Management Permissions + +HCP Terraform has three levels of team management permissions: manage membership, manage teams, and manage organization access. Each permission level grants users the ability to perform specific actions and each progressively requires prerequisite permissions. + +For example, to grant a user the manage teams permission, that user must already have manage membership permissions. To grant a user the manage organization access permission, a user must have both manage teams and manage membership permissions. + +#### Manage Membership + +Allows members to invite users to the organization, remove users from the organization, and add or remove users from teams within the organization. + +This permission grants the ability to view the list of users within the organization, and to view the organization access of other visible teams. It does not permit the creation of teams, the ability to modify the settings of existing teams, or the ability to view secret teams. + +In order to modify the membership of a team, a user with Manage Membership permissions must have visibility into the team (i.e. the team must be ["Visible"](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility), or the user must be on the team). +In order to remove a user from the organization, the holder of this permission must have visibility into all of the teams which the user is a member of. + +~> This permission is intended to allow owners of large organizations to delegate membership management to another trusted team, and should be granted to only teams of trusted users. **Assign with caution:** Users with this permission are able to add themselves to any visible team, and inherit the permissions of any visible team. + +#### Manage Teams + +Allows members to create, update, and delete teams, and generate, regenerate, and revoke tokens. + +This permission grants the ability to update a team's names, SSO IDs, and token management permissions, but does not allow access to organization settings. On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams. + +The manage teams permission confers all permissions granted by the manage membership permission. + +This permission allows owners of large organizations to delegate team management to another trusted team. You should only grant it to teams of trusted users. + +~> **Assign with caution**: Users with this permission can update or delete any visible team. Because this permission also confers the manage membership permission, a user with the manage teams permission can add themselves to any visible team. + +#### Manage Organization Access + +Allows members to update a team's organization access settings. + +On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams. This permission confers all of the permissions granted by the manage teams and manage membership permissions. + +This permission allows owners of large organizations to delegate team management to another trusted team. You should only grant it to teams of trusted users. + +~> **Assign with caution:** Members with this permission can update all organization access settings for any team visible to them. + +### Include Secret Teams + +Allows members access to secret teams at the level permitted by that user's team permissions setting. + +This permission acts as a modifier to existing team management permissions. Members with this permission can access secret teams up to the level permitted by other team management permissions. For example, if a user has permission to include secret teams and [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams), that user can create secret teams. + +### Allow Member Token Management + +Allows owners and members with [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permissions to enable and disable team token management for team members. This permission defaults to `true`. + +When member token management is enabled, members will be able to perform actions on team tokens, including generating and revoking a team token. + +When member token management is disabled, members will be unable to perform actions on team tokens, including generating and revoking a team token. + +## Permissions Outside HCP Terraform's Scope + +This documentation only refers to permissions that are managed by HCP Terraform itself. + +Since HCP Terraform integrates with other systems, the permissions models of those systems can also be relevant to the overall security model of your HCP Terraform organization. For example: + +- When a workspace is connected to a VCS repository, anyone who can merge changes to that repository's main branch can indirectly queue plans in that workspace, regardless of whether they have explicit permission to queue plans or are even a member of your HCP Terraform organization. (And when auto-apply is enabled, merging changes will indirectly apply runs.) +- If you use HCP Terraform's API to create a Slack bot for provisioning infrastructure, anyone able to issue commands to that Slack bot can implicitly act with that bot's permissions, regardless of their own membership and permissions in the HCP Terraform organization. +- When a run task sends a request to an integrator, it provides an access token that provides access depending on the run task stage: + - For post-plan, it provides access to the runs plan json and the run task callback + - All access tokens created for run tasks have a lifetime of 10 minutes + +When integrating HCP Terraform with other systems, you are responsible for understanding the effects on your organization's security. An integrated system is able to delegate any level of access that it has been granted, so carefully consider the conditions and events that will cause it to delegate that access. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/index.mdx new file mode 100644 index 0000000000..1be3015653 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/index.mdx @@ -0,0 +1,59 @@ +--- +page_title: Teams overview +description: >- + Teams are a group of users within an organization. Learn about managing teams, + team membership, team permissions, and more. +source: terraform-docs-common +--- + +[organizations]: /terraform/enterprise/users-teams-organizations/organizations + +[organization settings]: /terraform/enterprise/users-teams-organizations/organizations#organization-settings + +[users]: /terraform/enterprise/users-teams-organizations/users + +# Teams overview + +Teams are groups of HCP Terraform [users][] within an [organization][organizations]. If a user belongs to at least one team in an organization, they are considered a member of that organization. + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +An organization can [grant workspace permissions to teams](/terraform/enterprise/users-teams-organizations/teams/manage#managing-workspace-access) that allow its members to start Terraform runs, create workspace variables, read and write state, and more. Teams can only have permissions on workspaces within their organization, although individual users can belong to multiple teams in this and other organizations. + +> **Hands-on:** Try the [Manage Permissions in HCP Terraform](/terraform/tutorials/cloud/cloud-permissions?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. + +## Accessing teams with the API or TFE provider + +In addition to the HCP Terraform UI, you can use the following methods to manage teams: + +- [Teams API](/terraform/enterprise/api-docs/teams) to list, create, update, and delete teams +- [Team Members API](/terraform/enterprise/api-docs/team-members) to add and delete users from teams +- [Team Tokens API](/terraform/enterprise/api-docs/team-tokens) to generate and delete tokens and list an organization's team tokens +- [Team Access API](/terraform/enterprise/api-docs/team-access) to manage team access to one or more workspaces +- The `tfe` provider resources [`tfe_team`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/team), [`tfe_team_members`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/team_members), and `tfe_team_access` + +### API tokens + +Each team can have an API token not associated with a specific user. You can manage a team's API token from the **Organization settings > API Tokens > Team Token** page. You can create, regenerate, and delete team tokens on the API token page. Refer to [Team API Tokens](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) for details. + +## The owners team + +Every organization has an owners team, and members of the owners team are sometimes called organization owners. An organization's creator is the first member of its owner's team. You can add and remove other members in the same way as you can with other teams. In free organizations, the owner's team is limited to five members. In paid organizations, the size of the owner's team is unlimited. + +You cannot delete or leave the owner's team empty. If only one member in an owner's team exists, you must add another user before removing the current member. + +Refer to [organization owners](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) for more details about owners team permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Manage teams + +You can manage many things about teams, including creating and deleting a team, team membership, and team access to workspaces, projects, and organizations. Refer to [Manage teams](/terraform/enterprise/users-teams-organizations/teams/manage) to learn more. + +## Team notifications + +You can set up team notifications to notify team members on external systems whenever a particular action takes place. Refer to [Notifications](/terraform/enterprise/users-teams-organizations/teams/notifications) to learn more. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/manage.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/manage.mdx new file mode 100644 index 0000000000..63e0331297 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/manage.mdx @@ -0,0 +1,109 @@ +--- +page_title: Manage teams +description: >- + Learn how to manage team creation, team deletion, team membership, and team + access to workspaces, projects, and organizations. +source: terraform-docs-common +--- + +# Manage teams + +You can grant team management abilities to members of teams with either one of the manage teams or manage organization access permissions. Refer to [Team Permissions](/terraform/enterprise/users-teams-organizations/permissions#team-permissions) for details. + +[Organization owners](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) can also create teams, assign team permissions, or view the full list of teams. Other users can view any teams marked as visible within the organization, plus any secret teams they are members of. Refer to [Team Visibility](#team-visibility) for details. + +To manage teams, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to manage teams. +2. Choose **Settings** from the sidebar, then **Teams**. The **Team Management** page appears, containing a list of all teams within the organization. +3. Click a team to go to its settings page, which lists the team's settings and current members. Members that have [two-factor authentication](/terraform/enterprise/users-teams-organizations/2fa) enabled have a **2FA** badge. + +You can manage a team on its settings page by adding or removing members, changing its visibility, and controlling access to workspaces, projects, and the organization. + +## Create teams + +To create a new team, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to create a team. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click **Create a team**. +4. Enter a unique team **Name** and click **Create Team**. Team names can include numbers, letters, underscores (`_`), and hyphens (`-`). + +The new team's settings page appears, where you can add new members and grant permissions. + +## Delete teams + +~> **Important:** Team deletion is permanent, and you cannot undo it. + +To delete a team, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to delete a team. +2. Choose **Settings** from the sidebar, then **Teams**. The **Team Management** page appears, containing a list of all teams within the organization. +3. Click the team you want to delete to go to its settings page. +4. Click **Delete [team name]** at the bottom of the page. The **Deleting team "[team name]"** box appears. +5. Click **Yes, delete team** to permanently delete the team and all of its data from HCP Terraform. + +## Manage team membership + +Team structure often resembles your company's organizational structure. + +### Add users + +If the user is not yet in the organization, [invite them to join the organization](/terraform/enterprise/users-teams-organizations/organizations#users) and include a list of teams they should belong to in the invitation. Once the user accepts the invitation, HCP Terraform automatically adds them to those teams. + +To add a user that is already in the organization: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add a user to a team. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click on a team's name to go to its settings page. +4. Choose a user under **Add a New Team Member**. Use the text field to filter the list by username or email. +5. Click the user to add them to the team. HCP Terraform now displays the user under **Members**. + +### Remove users + +To remove a user from a team: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to remove a user from a team. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click the team to go to its settings page. +4. Click **...** next to the user's name and choose **Remove from team** from the menu. HCP Terraform removes the user from the list of team members. + +## Team visibility + +The settings under **Visibility** allow you to control who can see a team within the organization. To edit a team's visibility: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to view teams. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click on a team's name to navigate to its settings page. +4. Enable one of the following settings: + - **Visible:** Every user in the organization can see the team and its membership. Non-members have read-only access. + - **Secret:** The default setting is that only team members and organization owners can view a team and its membership. + +We recommend making the majority of teams visible to simplify workspace administration. Secret teams should only have +[organization-level permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) since workspace admins cannot manage permissions for teams they cannot view. + +## Manage workspace access + +You can grant teams various permissions on workspaces. Refer to [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) for details. + +HCP Terraform uses the most permissive permission level from your teams to determine what actions you can take on a particular resource. For example, if you belong to a team that only has permission to read runs for a workspace and another team with admin access to that workspace, HCP Terraform grants you admin access. + +HCP Terraform grants the most permissive permissions regardless of whether an organization, project, team, or workspace set those permissions. For example, if a team has permission to read runs for a given workspace and has permission to manage that workspace through the organization, then members of that team can manage that workspace. Refer to [organization permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) and [project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) for additional information. + +Another example is when a team has permission at the organization-level to read runs for all workspaces and admin access to a specific workspace. HCP Terraform grants the more permissive admin permissions to that workspace. + +To manage team permissions on a workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace where you want to set team permissions. +2. Choose **Settings** from the sidebar, then **Team Access**. +3. Click **Add team and permissions** to select a team and assign a pre-built or custom permission set. + +## Manage project access + +You can grant teams permissions to manage a project and the workspaces that belong to it. Refer to [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) for details. + +## Manage organization access + +Organization owners can grant teams permissions to manage policies, projects and workspaces, team and organization membership, VCS settings, private registry providers and modules, and policy overrides across an organization. Refer to [Organization Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/notifications.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/notifications.mdx new file mode 100644 index 0000000000..f13ba68a18 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/teams/notifications.mdx @@ -0,0 +1,132 @@ +--- +page_title: Manage team notifications +description: >- + Learn how to set up team notifications to notify team members on external + systems whenever a particular action takes place. +source: terraform-docs-common +--- + +# Manage team notifications + +HCP Terraform can use webhooks to notify external systems about run progress, change requests, and other events. Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs. + +@include 'tfc-package-callouts/notifications.mdx' + +You can configure an individual team notification to notify up to twenty teams. To set up notifications for teams using the API, refer to the [Notification API](/terraform/enterprise/api-docs/notification-configurations#team-notification-configuration). + +## Requirements + +To configure team notifications, you need the [**Manage teams**](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permissions for the team for which you want to configure notifications. + +## View notification configuration settings + +To view your current team notifications, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to view the team notifications of. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Select the team for which you want to view the notifications from your list of teams. +4. Select **Notifications** in the sidebar navigation. + +HCP Terraform displays a list of any notification configurations you have set up. A notification configuration defines how and when you want to send notifications, and once you enable that configuration, it can send notifications. + +### Update and enable notification configurations + +Each notification configuration includes a brief overview of each configuration’s name, type, the events that can trigger the notification, and the last time the notification was triggered. Clicking on a notification configuration opens a page where you can perform the following actions: + +- Enable your configuration to send notifications by toggling the switch. +- Delete a configuration by clicking **Delete notification**, then **Yes, delete notification configuration**. +- Test your notification’s configuration by clicking **Send test**. +- Click **Edit notification** to edit your notification configuration. + +After creating a notification configuration, you can only edit the following aspects of that configuration: + +1. The configuration’s name. +2. Whether this configuration notifies everyone on a team or specific members. +3. The workspace events that trigger notifications. You can choose from: + - **All events** triggers a notification for every event in your workspace. + - **No events** means that no workspace events trigger a notification. + - **Only certain events** lets you specify which events trigger a notification. + +After making any changes, click **Update notification** to save your changes. + +## Create and configure a notification + +To configure a new notification for a team or a user, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to create a team notification in. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Select the team you want to view the notifications for from your list of teams. +4. Select **Notifications** in the sidebar navigation. +5. Click **Create a notification**. + +You must complete the following fields for all new notification configurations: + +1. The **Destination** where HCP Terraform should deliver either a generic or a specifically formatted payload. Refer to [Notification payloads](#notification-payloads) for details. +2. The display **Name** for this notification configuration. +3. If you configure an email notification, you can optionally specify which **Email Recipients** will receive this notification. +4. If you choose to configure a webhook, you must also specify: + - A **Webhook URL** for the destination of your webhook payload. Your URL must accept HTTP or HTTPS `POST` requests and be able to use the chosen payload type. + - You can optionally configure a **Token** as an arbitrary secret string that HCP Terraform will use to sign its notification webhooks. Refer to [Notification authenticity](#notification-authenticity) for details. You cannot view the token after you save the notification configuration. +5. If you choose to specify either a **Slack** or **Microsoft Teams** notification, you must also configure your webhook URL for either service. For details, refer to Slack's documentation on [creating an incoming webhook](https://api.slack.com/messaging/webhooks#create_a_webhook) and Microsoft's documentation on [creating a workflow from a channel in teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-channel-in-teams-242eb8f2-f328-45be-b81f-9817b51a5f0e). +6. Specify which [**Workspace events**](#workspace-events) should trigger this notification. +7. After you finish configuring your notification, click **Create a notification**. + +Note that if you are create an email notification, you must have [**Manage membership**](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permissions on a team to select users from that team as email recipients. + +### Workspace events + +HCP Terraform can send notifications for all workspace events, no workspace events, or specific events. The following events are available for you to specify: + +| Event | Description | +| :-------------- | :-------------------------------------------------------------------------------------------------------------------------- | +| Change Requests | HCP Terraform will notify this team whenever someone creates a change request on a workspace to which this team has access. | + +## Enable and verify a notification + +To configure HCP Terraform to stop sending notifications for a notification configuration, disable the **Enabled** setting on a configuration's detail page . + +HCP Terraform enables notifications for email configurations by default. Before enabling any webhook notifications, HCP Terraform attempts to verify the notification’s configuration by sending a test message. If the test succeeds, HCP Terraform enables the notification. + +To verify a notification configuration, the destination must respond with a `2xx` HTTP code. If verification fails, HCP Terraform does not enable the configuration and displays an error message. + +For successful and unsuccessful verifications, click the **Last Response** box to view more information about the verification results. You can also send additional test messages by clicking **Send a Test**. + +## Notification Payloads + +Notification payloads contain different attributes depending on the integration you specified when configuring that notification. + +### Slack + +Notifications to Slack contain the following information: + +- Information about the change request, including the username and avatar of the person who created the change request. +- The event that triggered the notification and the time that event occurred. + +### Microsoft Teams + +Notifications to Microsoft Teams contain the following information: + +- Information about the change request, including the username and avatar of the person who created the change request. +- The event that triggered the notification and the time that event occurred. + +### Email + +Email notifications contain the following information: + +- Information about the change request, including the username and avatar of the person who created the change request. +- The event that triggered the notification and the time that event occurred. + +### Generic + +A generic notification contains information about the event that triggered it and the time that the event occurred. You can refer to the complete generic notification payload in the [API documentation](/terraform/enterprise/api-docs/notification-configurations#notification-payload). + +You can use some of the values in the payload to retrieve additional information through the API, such as: + +- The [workspace ID](/terraform/enterprise/api-docs/workspaces#list-workspaces) +- The [organization name](/terraform/enterprise/api-docs/organizations#show-an-organization) + +## Notification Authenticity + +Slack notifications use Slack's own protocols to verify HCP Terraform's webhook requests. + +Generic notifications can include a signature to verify the request. For notification configurations that include a secret token, HCP Terraform's webhook requests include an `X-TFE-Notification-Signature` header containing an HMAC signature computed from the token using the SHA-512 digest algorithm. The notification’s receiving service is responsible for validating the signature. For more information and an example of how to validate the signature, refer to the [API documentation](/terraform/enterprise/api-docs/notification-configurations#notification-payload). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/users.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/users.mdx new file mode 100644 index 0000000000..aa24a43750 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/users-teams-organizations/users.mdx @@ -0,0 +1,215 @@ +--- +page_title: Create and manage users in Terraform Enterprise +description: Learn how to create and manage users in Terraform Enterprise. +source: terraform-docs-common +--- + +[organizations]: /terraform/enterprise/users-teams-organizations/organizations + +[teams]: /terraform/enterprise/users-teams-organizations/teams + +[invite]: /terraform/enterprise/users-teams-organizations/organizations#users + +[owners]: /terraform/enterprise/users-teams-organizations/teams#the-owners-team + +# Create and manage users + +User accounts belong to individual people. Each user can be part of one or more [teams](/terraform/enterprise/users-teams-organizations/teams), which are granted permissions on workspaces within an organization. A user can be a member of multiple [organizations][]. + +## API + +Use the [Account API](/terraform/enterprise/api-docs/account) to get account details, update account information, and change your password. + + + +## Log in with a HashiCorp Cloud Platform account + +We recommend using a [HashiCorp Cloud Platform (HCP)](https://portal.cloud.hashicorp.com/sign-up) account to log in to HCP Terraform. Your HCP Account grants access to every HashiCorp product and the Terraform Registry. If you use an HCP Account, you manage account settings like multi-factor authentication and password resets from within HCP instead of the HCP Terraform UI. + +To log in with your HCP account, navigate to [HCP Terraform](https://app.terraform.io/) and click **Continue with HCP account**. HCP Terraform may ask if you want to link your account. + +### Linking HCP and HCP Terraform accounts + +The first time you log in with your HCP credentials, HCP Terraform searches for an existing HCP Terraform account with the same email address. If you have an unlinked account, HCP Terraform asks if you want to link it to your HCP account. Otherwise, if no account matches your HCP account's email address, HCP Terraform creates and automatically links a new HCP Terraform account to your HCP account. + +> **Note**: You can only log in with your HCP credentials after linking your HCP and HCP Terraform accounts. We do not recommend linking your account if you use an SSO provider to log in to HCP Terraform because linking your account may conflict with your existing SSO configuration. + +The only way to log in with your old HCP Terraform credentials is to unlink your HCP Terraform and HCP accounts. If HCP Terraform generated an account for you, you cannot unlink that account from your HCP account. You can unlink a pre-existing HCP Terraform account on the [HCP Account Linking page](#hcp-account-linking) in your **Account settings**. + + + +## Creating an account + +To use HCP Terraform or Enterprise, you must create an account through one of the following methods: + +- **Invitation Email:** When a user sends you an invitation to join an existing HCP Terraform organization, the email includes a sign-up link. After you create an account, you can automatically join that organization and can begin using HCP Terraform. +- **Sign-Up Page:** Creating an account requires a username, an email address, and a password. [Sign up on HCP Terraform](https://app.terraform.io/public/signup/account) or if you have a Terraform Enterprise instance, go to `https:///public/signup/account`. + +After you create an account, you do not belong to any organizations. To begin using HCP Terraform, you can either [create an organization](/terraform/enterprise/users-teams-organizations/organizations#creating-organizations) or ask an organization owner to send you an invitation email to join their organization. + + + +We recommend logging into HCP Terraform [with your HCP account](#log-in-with-your-hashicorp-cloud-platform-account) instead of creating a separate HCP Terraform account. + + + +## Joining organizations and teams + +An organization owner or a user with [**Manage Membership**](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permissions enabled must [invite you to join their organization](/terraform/enterprise/users-teams-organizations/organizations#users) and [add you to one or more teams](/terraform/enterprise/users-teams-organizations/teams/manage#manage-team-membership). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +HCP Terraform sends user invitations by email. If the invited email address matches an existing HCP Terraform account, the invitee can join the organization with that account. Otherwise, they must create a new account and then join the organization. + +## Site admin permissions + +On Terraform Enterprise instances, some user accounts have a special site admin permission that allows them to administer the entire instance. + +Admin permissions are distinct from normal organization-level permissions, and they apply to a different set of UI controls and API endpoints. Admin users can administer any resource across the instance when using the site admin pages or the [admin API](/terraform/enterprise/api-docs/admin), but they have normal user permissions when using an organization's standard UI controls and API endpoints. These normal user permissions are determined by team membership. + +Refer to [Administering Terraform Enterprise](/terraform/enterprise/admin) for more details. + +## Account settings + +To view your settings page, click your user icon and select **Account settings**. Your **Profile** page appears, showing your username, email address, and avatar. + +### Profile + +Click **Profile** in the sidebar to view and edit the username and email address associated with your HCP Terraform account. + +~> **Important:** HCP Terraform includes your username in URL paths to resources. If external systems make requests to these resources, you must update them before you change your username. + +HCP Terraform uses [Gravatar](http://en.gravatar.com) to display a user icon if you have associated one with your email address. Refer to the [Gravatar documentation](http://en.gravatar.com/support/) for details about changing your user icon. + +### Sessions + +Click **Sessions** in the sidebar to view a list of sessions associated with your HCP Terraform account. You can revoke any sessions you do not recognize. + + + +There are two types of Terraform accounts, standalone HCP Terraform accounts and HCP Terraform accounts linked to HCP accounts. + +### Idle session timeout + +HCP Terraform automatically terminates user sessions if there has been no end-user activity for a certain time period: + +- Standalone HCP Terraform accounts can stay idle and valid for up to 14 days by default +- HCP Terraform accounts linked to an HCP account follow the HCP defaults and can stay idle for 1 hour by default + +After HCP Terraform terminates a session, you can resume it by logging back in through the HCP Terraform portal. This is a security measure to prevent unauthorized access to unmonitored devices. + +-> **Note:** HCP Terraform organization owners can reduce the idle session timeout for an organization in the authentication settings for standalone HCP Terraform accounts, but cannot modify settings for HCP Terraform accounts linked to HCP accounts. + +### Forced re-authentication + +Forced re-authentication (e.g., “remember for”) makes a user re-authenticate, regardless of activity. This is a security measure to force a new identity verification to access sensitive IT and data managed by HCP Terraform. In this case, the user must re-authenticate their credentials and may be asked to verify 2FA/MFA again. + +- By default, standalone HCP Terraform accounts are forced to re-authenticate every 14 days +- By default, HCP Terraform accounts linked to an HCP account follow the HCP defaults and are forced to re-authenticate every 48 hours + +-> **Note:** HCP Terraform organization owners can reduce the idle session timeout for standalone HCP Terraform accounts, but cannot modify settings for HCP Terraform accounts linked to HCP accounts. + +### Impact to user experience + +The default re-authentication defaults force users to re-authenticate at the beginning of each work week (Monday through Friday). Note that several actions immediately terminate active sessions, including: + +- Manually logging out of the HCP or HCP Terraform portals +- Clearing browser session/cookies +- Closing all active browser windows + +Any of these actions requires you to re-authenticate regardless of session timeout settings. + + + +### Organizations + +Click **Organizations** in the sidebar to view a list of the organizations where you are a member. If you are on the [owners team][owners], the organization is marked with an **OWNER** badge. + +To leave an organization, click the ellipses (**...**) next to the organization and select **Leave organization**. You do not need permission from the owners to leave an organization, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or [delete the organization](/terraform/enterprise/users-teams-organizations/organizations#general). + +### Password + +Click **Password** in the sidebar to change your password. + +-> **Note:** Password management is not available if your Terraform Enterprise instance uses [SAML single sign on](/terraform/enterprise/saml/configuration). +-> **Note:** Passwords must be at least 10 characters in length, and you can use any type of character. Password management is not available if your Terraform Enterprise instance uses [SAML single sign on](/terraform/enterprise/saml/configuration). + +### Two-factor authentication + +Click **Two Factor Authentication** in the sidebar to enable two-factor authentication. Two-factor authentication requires a TOTP-compliant application or an SMS-capable phone number. An organization can set policies that require two-factor authentication. + +Refer to [Two-Factor Authentication](/terraform/enterprise/users-teams-organizations/2fa) for details. + + + +### HCP account linking + +Click **HCP Account Linking** in the sidebar to unlink your HCP Terraform from your HCP Account. You cannot unlink an account that HCP Terraform autogenerated during the linking process. Refer to [Linked HCP and HCP Terraform Accounts](#linked-hcp-and-hcp-terraform-accounts) for more details. + +After you unlink, you can begin using your HCP Terraform credentials to log in. You cannot log in with your HCP account again unless you re-link it to your HCP Terraform account. + +### SSO identities + +Click **SSO Identities** in the sidebar to review and [remove SSO identity links](/terraform/enterprise/users-teams-organizations/single-sign-on/linking-user-account#remove-sso-identity-link) associated with your account. + +You have an SSO identity for every SSO-enabled HCP Terraform organization. HCP Terraform links each SSO identity to a single HCP Terraform user account. This link determines which account you can use to access each organization. + + + +### Tokens + +Click **Tokens** in the sidebar to create, manage, and revoke API tokens. HCP Terraform has three kinds of API tokens: user, team, and organization. Users can be members of multiple organizations, so user tokens work with any organization where the associated user is a member. Refer to [API Tokens](/terraform/enterprise/users-teams-organizations/api-tokens) for details. + +API tokens are required for the following tasks: + +- Authenticating with the [HCP Terraform API](/terraform/enterprise/api-docs). API calls require an `Authorization: Bearer ` HTTP header. +- Authenticating with the [HCP Terraform CLI integration](/terraform/cli/cloud/settings) or the [`remote` backend](/terraform/language/settings/backends/remote). These require a token in the CLI configuration file or in the backend configuration. +- Using [private modules](/terraform/enterprise/registry/using) in command-line runs on local machines. This requires [a token in the CLI configuration file](/terraform/enterprise/registry/using#authentication). + +Protect your tokens carefully because they contain the same permissions as your user account. For example, if you belong to a team with permission to read and write variables for a workspace, another user could use your API token to authenticate as your user account and also edit variables in that workspace. Refer to [permissions](/terraform/enterprise/users-teams-organizations/permissions) for more details. + +We recommend protecting your tokens by creating them with an expiration date and time. Refer to [API Token Expiration](/terraform/enterprise/users-teams-organizations/api-tokens#token-expiration) for details. + +#### Creating a token + + To create a new token: + +1. Click **Create an API token**. The **Create API token** box appears. +2. Enter a **Description** that explains what the token is for and click **Create API token**. +3. You can optionally enter the token's expiration date or time, or create a token that never expires. The UI displays a token's expiration date and time in your current time zone. +4. Copy your token from the box and save it in a secure location. HCP Terraform only displays the token once, right after you create it. If you lose it, you must revoke the old token and create a new one. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Revoking a token + +To revoke a token, click the **trash can** next to it. That token will no longer be able to authenticate as your user account. + +~> **Note**: HCP Terraform does not revoke a user API token's access to an organization when you remove the user from an SSO Identity Provider as the user may still be a member of the organization. To remove access to a user's API token, remove the user from the organization in the UI or with the [Terraform Enterprise provider](https://registry.terraform.io/providers/hashicorp/tfe/latest). + +### GitHub app OAuth token + +Click **Tokens** in the sidebar to manage your GitHub App token. This token lets you connect a workspaces to an available GitHub App installation. + +~> **Note:** Only an HCP Terraform user can own a GitHub App token. Team and Organization API tokens are not able to own a GitHub App token. + +A GitHub App token lets you: + +- Connect workspaces, policy sets, and registry modules to a GitHub App installation with the [HCP Terraform API](/terraform/enterprise/api-docs) and UI. +- View available GitHub App installations with the [HCP Terraform API](/terraform/enterprise/api-docs) and UI. + +After generating this token, you can use it to view information about your available installations for the Terraform Cloud GitHub App. + +#### Creating a GitHub app token + +To create a GitHub App token, click **Create a GitHub App token**. The **GitHub App authorization pop-up window** appears requesting authorization of the Terraform Cloud GitHub App. + +~> **Note:** This does not grant HCP Terraform access to repositories. + +#### Revoking a GitHub app token + +To revoke the GitHub App token, click the **ellipses button (...)**. The dropdown menu appears. Click the **Delete Token** option. This triggers a confirmation window to appear, which asks you to confirm that you want to revoke the token. Once confirmed, the token is revoked and you can no longer view GitHub App installations. + +#### Additional resources + +- [GitHub App permissions in HCP Terraform](/terraform/enterprise/vcs/github-app#github-permissions) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/azure-devops-server.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/azure-devops-server.mdx new file mode 100644 index 0000000000..841d8e7ecb --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/azure-devops-server.mdx @@ -0,0 +1,92 @@ +--- +page_title: Set up the Azure DevOps Server VCS provider +description: >- + Learn how to use an on-premises installation of Azure DevOps Server 2019 with + workspaces and private registry modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the Azure DevOps Server VCS provider + +These instructions are for using an on-premises installation of Azure DevOps Server 2019 for HCP Terraform's VCS features. [Azure DevOps Services has separate instructions,](/terraform/enterprise/vcs/azure-devops-services) as do the [other supported VCS providers.](/terraform/enterprise/vcs) + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Important Notes About Authentication + +HCP Terraform uses personal access tokens to connect to Azure DevOps Server. This access method requires some additional configuration and ongoing maintenance: + +- [IIS Basic Authentication must be disabled](https://docs.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/iis-basic-auth?view=azure-devops) on your Azure DevOps Server instance in order to use personal access tokens. +- Personal access tokens eventually expire, with a maximum allowed lifetime of one year. If HCP Terraform's token expires, it will be unable to connect to Azure DevOps Server until the token is replaced. To avoid a gap in service, do one of the following before the token expires: + - Update the expiration date of the existing token within Azure DevOps Server. + - Create a new token, and edit HCP Terraform's VCS connection to use it. + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add VCS Provider**. The **VCS Providers** page appears. + +4. Select **Azure DevOps** and then select **Azure DevOps Server** from the menu. The page moves to the next step. + +5. On the "Set up provider" step there are three textboxes. Enter an optional **Name** for this VCS connection. Enter the instance URL for your Azure DevOps Server in **HTTP URL** and **API URL** textboxes. Click the "Continue" button to continue to the next step. + +Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform. + +## Step 2: On Azure DevOps Server, Create a New Personal Access Token + +1. In a new browser tab, open your Azure DevOps Server instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have Project Collection Administrator access** to any projects containing repositories of Terraform configurations, since creating webhooks requires these permissions. It is not possible to create custom access roles with lower levels of privilege, as Microsoft does not currently allow delegation of this capability. + +2. Navigate to User settings -> Security -> Personal access tokens. + +3. Click the **New Token** button to generate a new personal access token with "Code (Read)" and "Code (Status)" scopes. (We recommend also granting access to "All accessible organizations.") + +4. Copy the generated token to your clipboard; you'll paste it in the next step. Leave this page open in a browser tab. + +## Step 3: Add the Personal Access Token on HCP Terraform + +1. On the "Configure settings" step there is one textbox. Enter your Azure DevOps Server **Personal Access Token** from Step 2. Click the "Continue" button to continue to the next step. + +## Step 4: Configure VCS Provider Scope on HCP Terraform (Optional) + +This step is optional. You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. + +To limit the scope of this VCS Provider: + +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click the **Update VCS Provider** button to save your selections. + +## Step 5: On Workstation, Create an SSH Key for HCP Terraform + +On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Azure DevOps Server. The exact command depends on your OS, but is usually something like `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"`. This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. + +This SSH key **must have an empty passphrase.** HCP Terraform cannot use SSH keys that require a passphrase. + +### Important Notes + +- Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Server; generate a new one or use an existing key reserved for service access. +- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it for authenticating to Azure DevOps Server. +- **Protect this private key carefully.** It can read code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +## Step 6: On Azure Devops Server, Add SSH Public Key + +1. Navigate to User settings -> Security -> SSH public keys on your Azure DevOps Server instance. + + ![Azure DevOps Server screenshot: the SSH keys page](/img/docs/azure-devops-server-public-keys.png) + +2. Click the **Add** button. Paste the text of the **SSH public key** you created in step 3 (from the `.pub` file) into the text field, then click the **Add key** button to confirm. + +## Step 7: On HCP Terraform, Add SSH Private Key + +1. Go back to your HCP Terraform browser tab and paste the text of the **SSH private key** you created in step 3 into the **Private SSH Key** text field of the "Set up SSH keypair" step. Click the "Add SSH key" button. + +## Finished + +At this point, Azure DevOps Server access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's repositories. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/azure-devops-services.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/azure-devops-services.mdx new file mode 100644 index 0000000000..959b1c6208 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/azure-devops-services.mdx @@ -0,0 +1,130 @@ +--- +page_title: Set up the Azure DevOps Services VCS provider +description: >- + Learn how to use Azure DevOps Services with workspaces and private registry + modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the Azure DevOps Services VCS provider + +These instructions are for using `dev.azure.com` for HCP Terraform's VCS features. [Other supported VCS providers](/terraform/enterprise/vcs) have separate instructions. + +This page explains the four main steps required to connect HCP Terraform to your Azure DevOps Services VCS: + +1. Create a new connection in HCP Terraform and get the callback URL. +2. On your VCS, register your HCP Terraform organization as a new application. Provide the callback URL and get the application ID and key. +3. Provide HCP Terraform with the application ID and key. Then, request VCS access. +4. On your VCS, approve the access request from HCP Terraform. + +~> **Important:** HCP Terraform only supports Azure DevOps connections that use the `dev.azure.com` domain. If your Azure DevOps project uses the older `visualstudio.com` domain, you must migrate using the [steps in the Microsoft documentation](https://docs.microsoft.com/en-us/azure/devops/release-notes/2018/sep-10-azure-devops-launch#switch-existing-organizations-to-use-the-new-domain-name-url). + +## Requirements + +Configuring a new VCS provider requires permission to [manage VCS settings](/terraform/enterprise/users-teams-organizations/permissions#manage-vcs-settings) for the organization. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Before you begin, enable `Third-party application access via OAuth` in Azure DevOps Services settings. + +1. Log in to [Azure DevOps Services](https://dev.azure.com/). +2. Click **Organization settings**. +3. Click **Policies** under **Security**. +4. Enable the **Third-party application access via OAuth** setting. + + ![Azure DevOps Services Screenshot: Policies Third-party application access via Oauth](/img/docs/azure-devops-services-oauth-policies.png) + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add VCS Provider**. The **VCS Providers** page appears. + +4. Select **Azure DevOps** and then select **Azure DevOps Services** from the menu. The page moves to the next step. + +Leave this page open in a browser tab. You will copy values from this page into Azure DevOps in the next step, and in later steps you will continue configuring HCP Terraform. + +## Step 2: From your Azure DevOps Services Profile, Create a New Application + +1. In a new browser tab, open your [Azure DevOps Services Profile](https://aex.dev.azure.com), and log in to your Azure DevOps Services account if necessary. A page with a list of your organizations appears. + + ~> **Important:** The Azure DevOps Services account you use for connecting HCP Terraform must have Project Collection Administrator access to any projects containing repositories of Terraform configurations, since creating webhooks requires admin permissions. It is not possible to create custom access roles with lower levels of privilege, as Microsoft does not currently allow delegation of this capability. If you're unable to load the link above, you can create a new application for the next step at one of the following links: `https://aex.dev.azure.com/app/register?mkt=en-US` or `https://app.vsaex.visualstudio.com/app/register?mkt=en-US`. + +2. Go into your preferred organization. + +3. Click your user icon and then click the **ellipses (...) ** and select **User settings**. + +4. From the User settings menu, click **Profile**. Your profile page appears. + +5. Click **Authorizations**. The Authorized OAuth Apps page appears. + +6. Click the link to register a new app. A form appears asking for your company and application information. + +7. Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear and includes controls for copying values to your clipboard. Here is an example: + + | Field name | Value | + | -------------------------- | ----------------------------------------------------------------------------- | + | Company name | HashiCorp | + | Application Name | HCP Terraform (``) | + | Application website | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + | Authorization callback URL | `https://app.terraform.io/` | + + In the **Authorized scopes** section, select only **Code (read)** and **Code (status)** and then click **Create Application.** + + ![Azure DevOps Services Screenshot: Required permissions when creating a new application in your Azure DevOps Services Profile](/img/docs/azure-devops-services-application-permissions.png) + + ~> **Important:** Do not add any additional scopes beyond **Code (read)** and **Code (status),** as this can prevent HCP Terraform from connecting. Note that these authorized scopes cannot be updated after the application is created; to fix incorrect scopes you must delete and re-create the application. + +8. After creating the application, the next page displays its details. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **App ID** and **Client Secret** from this page. + + If you accidentally close this details page and need to find it later, you can reach it from the **Applications and Services** links in your profile. + +## Step 3: On HCP Terraform, Set up Your Provider + +1. (Optional) Enter a **Name** for this VCS connection. + +2. Enter your Azure DevOps Services application's **App ID** and **Client Secret**. These can be found in the application's details, which should still be open in the browser tab from Step 2. + +3. Click **Connect and continue.** This takes you to a page on Azure DevOps Services, asking whether you want to authorize the app. Click the **Accept** button and you'll be redirected back to HCP Terraform. + + -> **Note:** If you receive a 404 error from Azure DevOps Services, it likely means your callback URL has not been configured correctly. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new Azure DevOps Services client. + +### If You Need to Limit the Scope of this VCS Provider: + +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need an SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Services; generate a new one or use an existing key reserved for service access. +- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to Azure DevOps Services. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Azure DevOps Services.com. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the Azure DevOps Services account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button. + +## Finished + +At this point, Azure DevOps Services access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's repositories. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/bitbucket-cloud.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/bitbucket-cloud.mdx new file mode 100644 index 0000000000..41e33f8676 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/bitbucket-cloud.mdx @@ -0,0 +1,127 @@ +--- +page_title: Set up the Bitbucket Cloud VCS provider +description: >- + Learn how to use Bitbucket Cloud with workspaces and private registry modules + in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the Bitbucket Cloud VCS provider + +This topic describes how to connect Bitbucket Cloud to HCP Terraform. Bitbucket Cloud is the cloud-hosted version of Bitbucket. For self-hosted Bitbucket Data Center instances, refer to [Configuring Bitbucket Data Center Access](/terraform/enterprise/vcs/bitbucket-data-center). Refer to [Connecting VCS Providers to HCP Terraform](/terraform/enterprise/vcs) for other supported VCS providers. + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get callback URL. | +| Register your HCP Terraform organization as a new app. Provide callback URL. Get ID and key. |   | +|   | Provide HCP Terraform with ID and key. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the Bitbucket Cloud-specific versions of these steps. + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add VCS Provider**. The **VCS Providers** page appears. + +4. Select **Bitbucket** and then select **Bitbucket Cloud** from the menu. The page moves to the next step. + +Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform. + +## Step 2: On Bitbucket Cloud, Create a New OAuth Consumer + +1. In a new browser tab, open [Bitbucket Cloud](https://bitbucket.org) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. + +2. Navigate to Bitbucket's "Add OAuth Consumer" page. + + This page is located at `https://bitbucket.org//workspace/settings/oauth-consumers/new`. You can also reach it through Bitbucket's menus: + + - Click your profile picture and choose the workspace you want to access. + - Click "Settings". + - Click "OAuth consumers," which is in the "Apps and Features" section. + - On the OAuth settings page, click the "Add consumer" button. + +3. This page has a form with several text fields and checkboxes. + + Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the text fields as follows: + + | Field | Value | + | ------------ | ----------------------------------------------------------------------------- | + | Name | HCP Terraform (``) | + | Description | Any description of your choice. | + | Callback URL | `https://app.terraform.io/` | + | URL | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + + Ensure that the "This is a private consumer" option is checked. Then, activate the following permissions checkboxes: + + | Permission type | Permission level | + | --------------- | ---------------- | + | Account | Write | + | Repositories | Admin | + | Pull requests | Write | + | Webhooks | Read and write | + +4. Click the "Save" button, which returns you to the OAuth settings page. + +5. Find your new OAuth consumer under the "OAuth Consumers" heading, and click its name to reveal its details. + + Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Key** and **Secret.** + +## Step 3: On HCP Terraform, Set up Your Provider + +1. Enter the **Key** and **Secret** from the previous step, as well as an optional **Name** for this VCS connection. + +2. Click "Connect and continue." This takes you to a page on Bitbucket Cloud asking whether you want to authorize the app. + +3. Click the blue "Grant access" button to proceed. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new Bitbucket Cloud client. + +### If You Need to Limit the Scope of this VCS Provider: + +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need an SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and Bitbucket Cloud; generate a new one or use an existing key reserved for service access. +- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to Bitbucket Cloud. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Bitbucket Cloud. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the Bitbucket Cloud account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button. + +## Finished + +At this point, Bitbucket Cloud access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/bitbucket-data-center.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/bitbucket-data-center.mdx new file mode 100644 index 0000000000..24d13c9886 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/bitbucket-data-center.mdx @@ -0,0 +1,128 @@ +--- +page_title: Set up the Bitbucket Data Center VCS provider +description: >- + Learn how to use Bitbucket Data Center with workspaces and private registry + modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the Bitbucket Data Center VCS provider + +This topic describes how to connect Bitbucket Data Center to HCP Terraform. For instructions on how to connect Bitbucket Cloud, refer to [Configuring Bitbucket Cloud Access](/terraform/enterprise/vcs/bitbucket-cloud). Refer to [Connecting VCS Providers to HCP Terraform](/terraform/enterprise/vcs) for other supported VCS providers. + +**Bitbucket Server is deprecated**. Atlassian ended support for Bitbucket Server on February 15, 2024, and recommends using either Bitbucket Data Center (v8.0 or newer) or Bitbucket Cloud instead. Refer to the [Atlassian documentation](https://bitbucket.org/blog/cloud-migration-benefits) for additional information. + +HCP Terraform will end support Bitbucket Server on August 15, 2024. Terraform Enterprise will also end support for Bitbucket Server in Terraform Enterprise v202410. [Contact HashiCorp support](https://support.hashicorp.com/hc/en-us) if you have any questions regarding this change. + +## Overview + +The following steps provide an overview of how to connect HCP Terraform and Terraform Enterprise to Bitbucket Data Center: + +1. Add a new VCS provider to HCP Terraform or Enterprise. +2. Create a new application link in Bitbucket. +3. Create an SSH key pair. SSH keys must have an empty passphrase because HCP Terraform cannot use SSH keys that require a passphrase. +4. Add an SSH key to Bitbucket. You must complete this step as a non-administrator user in Bitbucket. +5. Add the private SSH key to Terraform. + +## Requirements + +- You must have permission to manage VCS settings for the organization. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +- You must have OAuth authentication credentials for Bitbucket Data Center. + +- Your instance of Bitbucket Data Center must be internet-accessible on its SSH and HTTP(S) ports. This is because HCP Terraform must be able to contact Bitbucket Data Center over both SSH and HTTP or HTTPS during setup and during normal operation. + +- HCP Terraform must have network connectivity to Bitbucket Data Center instances. Note that [Bitbucket Data Center's default ports](https://confluence.atlassian.com/bitbucketserverkb/which-ports-does-bitbucket-server-listen-on-and-what-are-they-used-for-806029586.html) are `7999` for SSH and `7990` for HTTP. Check your configuration to confirm your BitBucket instance's real ports. + +## Add a new VCS provider to Terraform + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add VCS Provider**. The **VCS Providers** page appears. + +4. Choose **Bitbucket Data Center** from the **Bitbucket** drop-down menu. + +5. (Optional) Enter a **Name** for this VCS connection. + +6. Specify the URL of your Bitbucket Data Center instance in the **HTTP URL** and **API URL** fields. If the context path is not set for your Bitbucket Data Center instance, the **API URL** is the same as the **HTTP URL**. Refer to the [Atlassian documentation](https://confluence.atlassian.com/bitbucketserver/moving-bitbucket-server-to-a-different-context-path-776640153.html) for additional information. Specify the following values if the context path is set for your Bitbucket Data Center instance: + + - Set the **HTTP URL** field to your Bitbucket Data Center instance URL and add the context path: `https:///`. + - Set the **API URL** field to your Bitbucket Data Center instance URL: `https://`. + + By default, HCP Terraform uses port `80` for HTTP and `443` for HTTPS. If Bitbucket Data Center is configured to use non-standard ports or is behind a reverse proxy, you may need to include the port number in the URL. + +7. You can either generate new consumer and public keys that you can use to create a new application link in Bitbucket Data Center described in [Create an application link](#create-an-application-link) or use keys from an existing application link: + - To generate new keys, click **Continue**. Do not leave this screen until you have copied the key values. + - To use existing keys, enable the **Use Custom Keys** option and enter them into the fields. + +## Create an application link + +1. Log into Bitbucket Data Center as an admin. + +2. Open the **Application Links** administration page using the navigation or by entering `https:///plugins/servlet/applinks/listApplicationLinks` in your browser's address bar. + +3. Click **Application Links** in the sidebar, then click **Create new link**. + +4. Choose **Atlassian product** as the link type. This option also works for external applications and lets you continue to use OAuth 1.0 integrations. + +5. Enter `https://app.terraform.io` or the hostname of your Terraform Enterprise instance when prompted. You can only specify the main URL once. To connect multiple HCP Terraform organizations to the same Bitbucket Data Center instance, enter the organization URL when creating the link instead. The organization URL is the HCP Terraform URL or Terraform Enterprise hostname appended with `/app/`. + +6. When prompted, confirm that you wish to use the URL as entered. If you specified HCP Terraform's main URL, click **Continue**. If you specified an organization URL, enable the **Use this URL** option and then click **Continue**. + +7. In the **Link applications** dialog, configure the following settings: + + - Specify `HCP Terraform ` in the **Application Name** field + - Choose **Generic Application** from the **Application Type** drop-down menu + - Enable the **Create incoming link** option + + Leave all the other fields empty. + +8. Click **Continue**. The **Link applications** screen progresses to the second configuration screen. + +9. In the **Consumer Key** and **Public Key** fields, enter the key values you created in the [Add a new VCS provider to Terraform](#add-a-new-vcs-provider-to-terraform) instructions. + +10. In the **Consumer Name** field, enter `HCP Terraform ()`. + +11. Click **Continue**. Bitbucket prompts you to authorize Terraform to make changes. Before you proceed, verify that you are logged in with the user account that HCP Terraform will use to access Bitbucket and not as a Bitbucket administrator. If Bitbucket returns a 500 error instead of the authorization screen, Terraform may have been unable to reach your Bitbucket Data Center instance. + +12. Click **Allow** and enter the SSH key when prompted. + +## Create an SSH key for Terraform + +On a secure workstation, create an SSH keypair that HCP Terraform or Terraform Enterprise can use to connect to Bitbucket Data Center. The command for generating SSH keys depends on your OS. The following example for Linux creates a `service_terraform` file with the private key and a `service_terraform.pub` file with the public key: + +```shell-session +$ ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise" +``` + +Do not specify a passphrase because Terraform cannot use SSH keys that require a passphrase. + +## Add an SSH key to Bitbucket + +In the following steps, you must provide HCP Terraform with the private SSH key you created in [Create an SSH key for Terraform](#create-an-ssh-key-for-terraform). Although HCP Terraform does not display the text of the key to users after it is entered, it retains the key and uses it for authenticating to Bitbucket Data Center. + +1. If you are logged into Bitbucket Data Center as an administrator, log out before proceeding. +2. Log in with the account that you want to enable HCP Terraform or Terraform Enterprise to log in with. Many organizations use a dedicated service user account for this purpose. The account you use for connecting HCP Terraform must have admin access to any shared repositories of Terraform configurations because since creating webhooks requires admin permissions. Refer to [Requirements](#requirements) for additional information. +3. Open the **SSH keys** page and click the profile icon. +4. Choose **Manage account**. +5. Click **SSH keys** or enter `https:///plugins/servlet/ssh/account/keys` in the address bar to go to the **SSH keys** screen. +6. Click **Add key** and enter the SSH public key you created in [Create an SSH key for Terraform](#create-an-ssh-key-for-terraform) into the text field. Open the `.pub` file to get the key value. +7. Click **Add key** to finish adding the key. + +## Add an SSH private key + +Complete the following steps in HCP Terraform or Terraform Enterprise to request access to Bitbucket and add the SSH private key. + +1. Open the **SSH keys** settings page and click **Add a private SSH key**. A large text field appears. +2. Enter the text of the **SSH private key** you created in [Create an SSH key for Terraform](#create-an-ssh-key-for-terraform) and click **Add SSH Key**. + +## Next steps + +After completing these instructions, you can create Terraform workspaces based on your organization's shared repositories. Refer to the following resources for additional guidance: + +- [Creating Workspaces](/terraform/enterprise/workspaces/create) in HCP Terraform +- [Creating Workspaces](/terraform/enterprise/workspaces/create) in Terraform Enterprise diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/github-enterprise.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/github-enterprise.mdx new file mode 100644 index 0000000000..ffdc1dd99f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/github-enterprise.mdx @@ -0,0 +1,140 @@ +--- +page_title: Set up the GitHub Enterprise VCS provider +description: >- + Learn how to use an on-premise installation of GitHub Enterprise with + workspaces and private registry modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the GitHub Enterprise VCS provider + +These instructions are for using a self-hosted installation of GitHub Enterprise for HCP Terraform's VCS features. [GitHub.com has separate instructions,](/terraform/enterprise/vcs/github-enterprise) as do the [other supported VCS providers.](/terraform/enterprise/vcs) + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get callback URL. | +| Register your HCP Terraform organization as a new app. Provide callback URL. Get ID and key. |   | +|   | Provide HCP Terraform with ID and key. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the GitHub Enterprise versions of these steps. + +~> **Important:** HCP Terraform needs to contact your GitHub Enterprise instance during setup and during normal operation. For the SaaS version of HCP Terraform, this means GitHub Enterprise must be internet-accessible; for Terraform Enterprise, you must have network connectivity between your Terraform Enterprise and GitHub Enterprise instances. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +## Step 1: On HCP Terraform, begin adding a new VCS provider + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add a VCS provider**. The **Add VCS Provider** page appears. + +4. Select **GitHub** and then select **GitHub Enterprise** from the menu. The page moves to the next step. + +5. In the "Set up provider" step, fill in the **HTTP URL** and **API URL** of your GitHub Enterprise instance, as well as an optional **Name** for this VCS connection. + + | Field | Value | + | -------- | ------------------------------------------- | + | HTTP URL | `https://` | + | API URL | `https:///api/v3` | + +Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform. + +## Step 2: On GitHub, create a new OAuth application + +1. In a new browser tab, open your GitHub Enterprise instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. + +2. Navigate to GitHub's Register a New OAuth Application page. + + This page is located at `https:///settings/applications/new`. You can also reach it through GitHub's menus: + + - Click your profile picture and choose "Settings." + - Click "OAuth Apps" (under the "Developer settings" section). + - Click the "Register a new application" button. + +3. This page has a form with four text fields. + + Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the text fields as follows: + + | Field name | Value | + | -------------------------- | ----------------------------------------------------------------------------- | + | Application Name | HCP Terraform (``) | + | Homepage URL | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + | Application Description | Any description of your choice. | + | Authorization callback URL | `https://app.terraform.io/` | + +4. Click the "Register application" button, which creates the application and takes you to its page. + +5. Download this image of the HCP Terraform logo and upload it with the "Upload new logo" button or the drag-and-drop target. This optional step helps you identify HCP Terraform's pull request checks at a glance. + +6. Click the "Generate a new client secret" button. You will need this secret in the next step. + +7. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Client ID** and **Client Secret.** + +## Step 3: On HCP Terraform, set up your provider + +1. Enter the **Client ID** and **Client Secret** from the previous step. + +2. Click "Connect and continue." This takes you to a page on your GitHub Enterprise instance, asking whether you want to authorize the app. + +3. The authorization page lists any GitHub organizations this account belongs to. If there is a **Request** button next to the organization that owns your Terraform code repositories, click it now. Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization's access restrictions. See [About OAuth App access restrictions](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions). + + If it results in a 500 error, it usually means HCP Terraform was unable to reach your GitHub Enterprise instance. + +4. Click the green "Authorize ``" button at the bottom of the authorization page. GitHub might request your password or multi-factor token to confirm the operation. + +## Step 4: On HCP Terraform, configure advanced settings (optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If you don't need to configure advanced settings: + +1. Click the **Skip and finish** button. This returns you to HCP Terraform's VCS Providers page, which now includes your new GitHub Enterprise client. + +### If you need to limit the scope of this VCS provider: + +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click the **Update VCS Provider** button to save your selections. + +### If you need an SSH keypair: + +#### Important notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitHub Enterprise; generate a new one or use an existing key reserved for service access. +- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitHub Enterprise. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Github Enterprise. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitHub Enterprise account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button. + +## Step 5: Contact Your GitHub organization admins + +If your organization uses OAuth app access restrictions, you had to click a **Request** button when authorizing HCP Terraform, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before HCP Terraform can access your organization's shared repositories. + +If you're a GitHub administrator, check your email now and respond to the request; otherwise, contact whoever is responsible for GitHub accounts in your organization, and wait for confirmation that they've approved your request. + +## Finished + +At this point, GitHub access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared GitHub Enterprise repositories. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/github.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/github.mdx new file mode 100644 index 0000000000..0ffe1630c9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/github.mdx @@ -0,0 +1,145 @@ +--- +page_title: Set up the GitHub.com OAuth VCS provider +description: >- + Learn how to use GitHub.com with workspaces and private registry modules in + Terraform Enterprise with a per-organization OAuth connection. +source: terraform-docs-common +--- + +# Set up the GitHub.com OAuth VCS provider + +These instructions are for using GitHub.com for HCP Terraform's VCS features, using a per-organization OAuth connection with the permissions of one particular GitHub user. [GitHub Enterprise has separate instructions,](/terraform/enterprise/vcs/github-enterprise) as do the [other supported VCS providers.](/terraform/enterprise/vcs) + + + +For new users on HCP Terraform, we recommend using our [configuration-free GitHub App](/terraform/enterprise/vcs/github-app) to access repositories instead. + + + +For Terraform Enterprise site admins, you can create your own [GitHub App](/terraform/enterprise/admin/application/github-app-integration) to access repositories. + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| ---------------------------------------------------------------------------- | ----------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get callback URL. | +| Register your HCP Terraform organization as a new app. Provide callback URL. |   | +|   | Provide HCP Terraform with ID and key. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the GitHub versions of these steps. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +## Step 1: On HCP Terraform, begin adding a new VCS provider + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add a VCS provider**. The **Add VCS Provider** page appears. + +4. Select **GitHub** and then select **GitHub.com (Custom)** from the menu. The page moves to the next step. + +Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform. + +## Step 2: On GitHub, create a new OAuth application + +On the HCP Terraform **Add VCS Provider** page, click **register a new OAuth Application**. This opens GitHub.com in a new browser tab with the OAuth application settings pre-filled. + +Alternately, create the OAuth application manually on GitHub.com. + +### Manual steps + +1. In a new browser tab, open [github.com](https://github.com) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. + +2. Navigate to GitHub's [Register a New OAuth Application](https://github.com/settings/applications/new) page. + + This page is located at . You can also reach it through GitHub's menus: + + - Click your profile picture and choose "Settings." + - Click "Developer settings," then make sure you're on the "OAuth Apps" page (not "GitHub Apps"). + - Click the "New OAuth App" button. + +3. This page has a form with four text fields. + + Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the text fields as follows: + + | Field name | Value | + | -------------------------- | ----------------------------------------------------------------------------- | + | Application Name | HCP Terraform (``) | + | Homepage URL | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + | Application Description | Any description of your choice. | + | Authorization callback URL | `https://app.terraform.io/` | + +### Register the OAuth application + +1. Click the "Register application" button, which creates the application and takes you to its page. + +2. Download this image of the HCP Terraform logo and upload it with the "Upload new logo" button or the drag-and-drop target. This optional step helps you identify HCP Terraform's pull request checks at a glance. + +3. Click the **Generate a new client secret** button. You will need this secret in the next step. + +4. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Client ID** and **Client Secret.** + +## Step 3: On HCP Terraform, set up your provider + +1. Enter the **Client ID** and **Client Secret** from the previous step, as well as an optional **Name** for this VCS connection. + +2. Click "Connect and continue." This takes you to a page on GitHub.com, asking whether you want to authorize the app. + +3. The authorization page lists any GitHub organizations this account belongs to. If there is a **Request** button next to the organization that owns your Terraform code repositories, click it now. Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization's access restrictions. See [About OAuth App access restrictions](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions). + +4. Click the green "Authorize ``" button at the bottom of the authorization page. GitHub might request your password or multi-factor token to confirm the operation. + +## Step 4: On HCP Terraform, configure advanced settings (optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If you don't need to configure advanced settings: + +1. Click the **Skip and finish** button. This returns you to HCP Terraform's **VCS Providers** page, which now includes your new GitHub client. + +### If you need to limit the scope of this VCS provider: + +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click the **Update VCS Provider** button to save your selections. + +### If you need an SSH keypair: + +#### Important notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitHub; generate a new one or use an existing key reserved for service access. +- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitHub. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to GitHub.com. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitHub.com account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button. + +## Step 5: Contact your GitHub organization admins + +If your organization uses OAuth app access restrictions, you had to click a **Request** button when authorizing HCP Terraform, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before HCP Terraform can access your organization's shared repositories. + +If you're a GitHub administrator, check your email now and respond to the request; otherwise, contact whoever is responsible for GitHub accounts in your organization, and wait for confirmation that they've approved your request. + +## Finished + +At this point, GitHub access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared GitHub repositories. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/gitlab-com.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/gitlab-com.mdx new file mode 100644 index 0000000000..43bee92f73 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/gitlab-com.mdx @@ -0,0 +1,119 @@ +--- +page_title: Set up the GitLab.com VCS provider +description: >- + Learn how to use GitLab.com repositories with workspaces and private registry + modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the GitLab.com VCS provider + +These instructions are for using GitLab.com for HCP Terraform's VCS features. [GitLab CE and GitLab EE have separate instructions,](/terraform/enterprise/vcs/gitlab-eece) as do the [other supported VCS providers.](/terraform/enterprise/vcs) + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get redirect URI. | +| Register your HCP Terraform organization as a new app. Provide redirect URI. |   | +|   | Provide HCP Terraform with application ID and secret. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the GitLab.com versions of these steps. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add VCS Provider**. The **VCS Providers** page appears. + +4. Select **GitLab** and then select **GitLab.com** from the menu. The page moves to the next step. + +5. Locate the "Redirect URI" and copy it to your clipboard; you'll paste it in the next step. + +Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform. + +## Step 2: On GitLab, Create a New Application + +1. In a new browser tab, open [gitlab.com](https://gitlab.com) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have Maintainer access** to any shared repositories of Terraform configurations, since creating webhooks requires Maintainer permissions. Refer to [the GitLab documentation](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions) for details. + +2. Navigate to GitLab's [User Settings > Applications](https://gitlab.com/-/profile/applications) page. + + This page is located at . You can also reach it through GitLab's menus: + + - Click your profile picture and choose "Settings." + - Click "Applications." + +3. This page has a list of applications and a form for adding new ones. The form has two text fields and some checkboxes. + + Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the form as follows: + + | Field | Value | + | ----------------------- | ---------------------------------------------------------------------------------------------- | + | Name | HCP Terraform (``) | + | Redirect URI | `https://app.terraform.io/`, the redirect URI you copied from HCP Terraform | + | Confidential (checkbox) | ✔️ (enabled) | + | Scopes (all checkboxes) | api | + + +1. Click the "Save application" button, which creates the application and takes you to its page. + +2. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Application ID** and **Secret.** + +## Step 3: On HCP Terraform, Set up Your Provider + +1. Enter the **Application ID** and **Secret** from the previous step, as well as an option **Name** for this VCS connection. + +2. Click **Connect and continue.** This takes you to a page on GitLab.com, which asks if you want to authorize the app. + +3. Click the green **Authorize** button at the bottom of the authorization page. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new GitLab client. + +### If You Need to Limit the Scope of this VCS Provider: + +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need an SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitLab; generate a new one or use an existing key reserved for service access. +- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitLab. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to GitLab.com. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitLab.com account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button. + +## Finished + +At this point, GitLab.com access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/gitlab-eece.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/gitlab-eece.mdx new file mode 100644 index 0000000000..a4b484859d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/gitlab-eece.mdx @@ -0,0 +1,133 @@ +--- +page_title: Set up the GitLab EE and CE VCS provider +description: >- + Learn how to use on-premise installation of GitLab Enterprise Edition (EE) or + GitLab Community Edition (CE) with workspaces and private registry module in + Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the GitLab EE and CE VCS provider + +These instructions are for using an on-premise installation of GitLab Enterprise Edition (EE) or GitLab Community Edition (CE) for HCP Terraform's VCS features. [GitLab.com has separate instructions,](/terraform/enterprise/vcs/gitlab-com) as do the [other supported VCS providers.](/terraform/enterprise/vcs) + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get redirect URI. | +| Register your HCP Terraform organization as a new app. Provide redirect URI. Get ID and key. |   | +|   | Provide HCP Terraform with application ID and secret. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the on-premise GitLab versions of these steps. + +~> **Important:** HCP Terraform needs to contact your GitLab instance during setup and during normal operation. For the SaaS version of HCP Terraform, this means GitLab must be internet-accessible; for Terraform Enterprise, you must have network connectivity between your Terraform Enterprise and GitLab instances. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +-> **Version Note:** HCP Terraform supports GitLab versions 9.0 and newer. HashiCorp does not test older versions of GitLab with HCP Terraform, and they might not work as expected. Also note that, although we do not deliberately remove support for versions that have reached end of life (per the [GitLab Support End of Life Policy](https://docs.gitlab.com/ee/policy/maintenance.html#patch-releases)), our ability to resolve customer issues with end of life versions might be limited. + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Select **GitLab** and then select **GitLab Enterprise Edition** or **GitLab Community Edition** from the menu. The page moves to the next step. + +4. In the "Set up provider" step, fill in the **HTTP URL** and **API URL** of your GitLab Enterprise Edition or GitLab Community Edition instance, as well as an optional **Name** for this VCS connection. Click "Continue." + + | Field | Value | + | -------- | ------------------------------------------- | + | HTTP URL | `https://` | + | API URL | `https:///api/v4` | + + Note that HCP Terraform uses GitLab's v4 API. + +Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform. + +## Step 2: On GitLab, Create a New Application + +1. In a new browser tab, open your GitLab instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin (master) access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. Do not create the application as an administrative application not owned by a user; HCP Terraform needs user access to repositories to create webhooks and ingress configurations. + + ~> **Important**: In GitLab CE or EE 10.6 and up, you may also need to enable **Allow requests to the local network from hooks and services** on the "Outbound requests" section inside the Admin area under Settings (`/admin/application_settings/network`). Refer to [the GitLab documentation](https://docs.gitlab.com/ee/security/webhooks.html) for details. + +2. Navigate to GitLab's "User Settings > Applications" page. + + This page is located at `https:///profile/applications`. You can also reach it through GitLab's menus: + + - Click your profile picture and choose "Settings." + - Click "Applications." + +3. This page has a list of applications and a form for adding new ones. The form has two text fields and some checkboxes. + + Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the form as follows: + + | Field | Value | + | ------------------------------- | ---------------------------------------------- | + | Name | HCP Terraform (``) | + | Redirect URI | `https://app.terraform.io/` | + | Confidential (checkbox) | ✔️ (enabled) | + | Expire access tokens (checkbox) | (no longer required) | + | Scopes (all checkboxes) | api | + + -> **Note:** For previous versions of HCP Terraform and GitLab, we recommended disabling a setting called `Expire access tokens`. This action was required because Gitlab marked OAuth tokens as expired after 2 hours, but HCP Terraform only refreshed tokens after 6 hours. This setting does not exist on Gitlab v15+ and HCP Terraform now refreshes tokens more often. + +4. Click the "Save application" button, which creates the application and takes you to its page. + +5. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Application ID** and **Secret.** + +## Step 3: On HCP Terraform, Set up Your Provider + +1. On the "Configure settings" step on HCP Terraform, enter the **Application ID** and **Secret** from the previous step. + +2. Click **Connect and continue.** This takes you to a page on GitLab asking whether you want to authorize the app. Alternatively, if you are redirected to a 500 error, it usually means HCP Terraform was unable to reach your GitLab instance. + +3. Click the green **Authorize** button at the bottom of the authorization page. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up a PEM formatted SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new GitLab client. + +### If You Need to Limit the Scope of this VCS Provider: + +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need a PEM formatted SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitLab; generate a new one or use an existing key reserved for service access. +- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitLab. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create a PEM formatted SSH keypair that HCP Terraform can use to connect to GitLab. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitLab account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button. + +## Finished + +At this point, GitLab access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/index.mdx new file mode 100644 index 0000000000..bf7668e7c2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/index.mdx @@ -0,0 +1,140 @@ +--- +page_title: Connect to VCS Providers +description: >- + Version control system (VCS) connections integrate Terraform Enterprise into + your workflow. Learn how to automate Terraform runs when you commit changes to + your code. +source: terraform-docs-common +--- + +# Connect to VCS Providers + +HCP Terraform is more powerful when you integrate it with your version control system (VCS) provider. Although you can use many of HCP Terraform's features without one, a VCS connection provides additional features and improved workflows. In particular: + +- When workspaces are linked to a VCS repository, HCP Terraform can [automatically initiate Terraform runs](/terraform/enterprise/run/ui) when changes are committed to the specified branch. +- HCP Terraform makes code review easier by [automatically predicting](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) how pull requests will affect infrastructure. +- Publishing new versions of a [private Terraform module](/terraform/enterprise/registry/publish-modules) is as easy as pushing a tag to the module's repository. + +We recommend configuring VCS access when first setting up an organization, and you might need to add additional VCS providers later depending on how your organization grows. + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Supported VCS Providers + +HCP Terraform supports the following VCS providers: + + + +- [GitHub.com](/terraform/enterprise/vcs/github-app) + + + +- [GitHub App for TFE](/terraform/enterprise/admin/application/github-app-integration) +- [GitHub.com (OAuth)](/terraform/enterprise/vcs/github) +- [GitHub Enterprise](/terraform/enterprise/vcs/github-enterprise) +- [GitLab.com](/terraform/enterprise/vcs/gitlab-com) +- [GitLab EE and CE](/terraform/enterprise/vcs/gitlab-eece) +- [Bitbucket Cloud](/terraform/enterprise/vcs/bitbucket-cloud) +- [Bitbucket Data Center](/terraform/enterprise/vcs/bitbucket-data-center) +- [Azure DevOps Server](/terraform/enterprise/vcs/azure-devops-server) +- [Azure DevOps Services](/terraform/enterprise/vcs/azure-devops-services) + +Use the links above to see details on configuring VCS access for each supported provider. If you use another VCS that is not supported, you can build an integration via [the API-driven run workflow](/terraform/enterprise/run/api). + +## How HCP Terraform Uses VCS Access + +Most workspaces in HCP Terraform are associated with a VCS repository, which provides Terraform configurations for that workspace. To find out which repos are available, access their contents, and create webhooks, HCP Terraform needs access to your VCS provider. + +Although HCP Terraform's API lets you create workspaces and push configurations to them without a VCS connection, the primary workflow expects every workspace to be backed by a repository. + +To use configurations from VCS, HCP Terraform needs to do several things: + +- Access a list of repositories, to let you search for repos when creating new workspaces. +- Register webhooks with your VCS provider, to get notified of new commits to a chosen branch. +- Download the contents of a repository at a specific commit in order to run Terraform with that code. + +~> **Important:** HCP Terraform usually performs VCS actions using a designated VCS user account, but it has no other knowledge about your VCS's authorization controls and does not associate HCP Terraform user accounts with VCS user accounts. This means HCP Terraform's VCS user might have a different level of access to repositories than any given HCP Terraform user. Keep this in mind when selecting a VCS user, as it may affect your security posture in one or both systems. + +### Webhooks + +HCP Terraform uses webhooks to monitor new commits and pull requests. + +- When someone adds new commits to a branch, any HCP Terraform workspaces based on that branch will begin a Terraform run. Usually a user must inspect the plan output and approve an apply, but you can also enable automatic applies on a per-workspace basis. You can prevent automatic runs by locking a workspace. A run will only occur if the workspace has not previously processed a run for the commit SHA. +- When someone submits a pull request/merge request to a branch, any HCP Terraform workspaces based on that branch will perform a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) with the contents of the request and links to the results on the PR's page. This helps you avoid merging PRs that cause plan failures. + +~> **Important:** In Terraform Enterprise, integration with a SaaS VCS provider (GitHub.com, GitLab.com, Bitbucket Cloud, or Azure DevOps Services) requires ingress from the public internet. This lets the inbound web hooks reach Terraform Enterprise. You should also configure appropriate security controls, such as a Web Application Firewall (WAF). + +### SSH Keys + +For most supported VCS providers, HCP Terraform does not need an SSH key. This is because Terraform can do everything it needs with the provider's API and an OAuth token. The exceptions are Azure DevOps Server and Bitbucket Data Center, which require an SSH key for downloading repository contents. Refer to the setup instructions for [Azure DevOps Server](/terraform/enterprise/vcs/azure-devops-server) and [Bitbucket Data Center](/terraform/enterprise/vcs/bitbucket-data-center) for details. + +For other VCS providers, most organizations will not need to add an SSH private key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. + +For VCS providers where adding an SSH private key is optional, SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. + +If submodules will be cloned via SSH from a private VCS instance, SSH must be running on the standard port 22 on the VCS server. + +To add an SSH key to a VCS connection, finish configuring OAuth in the organization settings, and then use the "add a private SSH key" link on the VCS Provider settings page to add a private key that has access to the submodule repositories. When setting up a workspace, if submodules are required, select "Include submodules on clone". More at [Workspace settings](/terraform/enterprise/workspaces/settings). + +### Multiple VCS Connections + +If your infrastructure code is spread across multiple VCS providers, you can configure multiple VCS connections. You can choose which VCS connection to use whenever you create a new workspace. + +#### Scoping VCS Connections using Projects + +You can configure which projects can use repositories from a VCS connection. By default each VCS connection is enabled for all workspaces in the organization. If you need to limit which projects can use repositories from a given VCS connection, you can change this setting to enable the connection for only workspaces in the selected projects. + +## Configuring VCS Access + +HCP Terraform uses the OAuth protocol to authenticate with VCS providers. + +~> **Important:** Even if you've used OAuth before, read the instructions carefully. Since HCP Terraform's security model treats each _organization_ as a separate OAuth application, we authenticate with OAuth's developer workflow, which is more complex than the standard user workflow. + +The exact steps to authenticate are different for each VCS provider, but they follow this general order: + +| On your VCS | On HCP Terraform | +| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| Register your HCP Terraform organization as a new app. Get ID and key. |   | +|   | Tell HCP Terraform how to reach VCS, and provide ID and key. Get callback URL. | +| Provide callback URL. |   | +|   | Request VCS access. | +| Approve access request. |   | + +For complete details, click the link for your VCS provider: + +- [GitHub](/terraform/enterprise/vcs/github) +- [GitHub Enterprise](/terraform/enterprise/vcs/github-enterprise) +- [GitLab.com](/terraform/enterprise/vcs/gitlab-com) +- [GitLab EE and CE](/terraform/enterprise/vcs/gitlab-eece) +- [Bitbucket Cloud](/terraform/enterprise/vcs/bitbucket-cloud) +- [Bitbucket Data Center](/terraform/enterprise/vcs/bitbucket-data-center) +- [Azure DevOps Server](/terraform/enterprise/vcs/azure-devops-server) +- [Azure DevOps Services](/terraform/enterprise/vcs/azure-devops-services) + +-> **Note:** Alternatively, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + + + +### Private VCS + +You can use self-hosted HCP Terraform Agents to connect HCP Terraform to your private VCS provider, such as GitHub Enterprise, GitLab Enterprise, and BitBucket Data Center. For more information, refer to [Connect to Private VCS Providers](/terraform/enterprise/vcs/private). + + + +## Configure a VCS host for Terraform Enterprise + +You can configure Terraform Enterprise to be accessible over a primary and a secondary hostname so that you can federate workloads associated with your VCS. Refer to [Specify integration setttings](/terraform/enterprise/deploy/configuration/network#specify-integration-settings) for additional information. + +You must set up new VCS connections any time you update the VCS host configuration. When the VCS integration uses the secondary hostname, you should continue using it while setting up the new VCS connection. When setup is complete, you can use the primary hostname for all other activities. Refer to [`TFE_VCS_HOSTNAME_CHOICE` ](/terraform/enterprise/deploy/reference/configuration#tfe_vcs_hostname_choice) in the configuration reference for additional information. + +## Viewing events + +VCS events describe changes within your organization for VCS-related actions. The VCS events page only displays events from previously processed commits in the past 30 days. The VCS page indicates previously processed commits with the message, `"Processing skipped for duplicate commit SHA"`. + +Viewing VCS events requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +To view VCS events for your organization, go to your organization's settings and click **Events**. The **VCS Events** page appears. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/troubleshooting.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/troubleshooting.mdx new file mode 100644 index 0000000000..182c9ba0bb --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/vcs/troubleshooting.mdx @@ -0,0 +1,227 @@ +--- +page_title: Troubleshoot VCS providers in Terraform Enterprise +description: >- + Learn how to address common problems in VCS integrations for Terraform + Enterprise. +source: terraform-docs-common +--- + +# Troubleshoot VCS providers + +This page collects solutions to the most common problems our users encounter with VCS integration in HCP Terraform. + +## Azure DevOps + +### Required status checks not sending + +When configuring [status checks with Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/pr-status-policy) the web interface may auto populate Genre and Name fields (beneath "Status to check") with incorrect values that do not reflect what HCP Terraform is sending. +To function correctly as required checks the Genre must be populated with "Terraform Cloud" (or the first segment for a Terraform Enterprise install), and the remainder of the status check goes in the Name field. This requires using the "Enter genre/name separately" checkbox to not use the default configuration. + +In the example below the status check is named `Terraform Cloud/paul-hcp/gianni-test-1` and needs to be configured with Genre `Terraform Cloud` and Name `paul-hcp/gianni-test-1`. + +![Azure DevOps screenshot: configuring required status checks correctly](/img/docs/ado-required-status-check.png) + +With an older version of Azure DevOps Server it may be that the web interface does not allow entering the Genre and Name separately. In which case the status check will need to be created via the [API](https://learn.microsoft.com/en-us/rest/api/azure/devops/policy/configurations/create). + +## Bitbucket Data Center + +The following errors are specific to Bitbucket Data Center integrations. + +### Clicking "Connect organization ``" with Bitbucket Data Center raises an error message in HCP Terraform + +HCP Terraform uses OAuth 1 to authenticate the user to Bitbucket Data Center. The first step in the authentication process is for HCP Terraform to call Bitbucket Data Center to obtain a request token. After the call completes, HCP Terraform redirects you to Bitbucket Data Center with the request token. + +An error occurs when HCP Terraform calls to Bitbucket Data Center to obtain the request token but the request is rejected. Some common reasons for the request to be rejected are: + +- The API endpoint is unreachable; this can happen if the address or port is incorrect or the domain name doesn't resolve. +- The certificate used on Bitbucket Data Center is rejected by the HCP Terraform HTTP client because the SSL verification fails. This is often the case with self-signed certificates or when the Terraform Enterprise instance is not configured to trust the signing chain of the Bitbucket Data Center SSL certificate. + +To fix this issue, do the following: + +- Verify that the instance running Terraform Enterprise can resolve the domain name and can reach Bitbucket Data Center. +- Verify that the HCP Terraform client accepts the HTTPS connection to Bitbucket Data Center. This can be done by performing a `curl` from the Terraform Enterprise instance to Bitbucket Data Center; it should not return any SSL errors. +- Verify that the Consumer Key, Consumer Name, and the Public Key are configured properly in Bitbucket Data Center. +- Verify that the HTTP URL and API URL in HCP Terraform are correct for your Bitbucket Data Center instance. This includes the proper scheme (HTTP vs HTTPS), as well as the port. + +### Creating a workspace from a repository hangs indefinitely, displaying a spinner on the confirm button + +If you were able to connect HCP Terraform to Bitbucket Data Center but cannot create workspaces, it often means HCP Terraform isn't able to automatically add webhook URLs for that repository. + +To fix this issue: + +- Make sure you haven't manually entered any webhook URLs for the affected repository or project. Although the Bitbucket Web Post Hooks Plugin documentation describes how to manually enter a hook URL, HCP Terraform handles this automatically. Manually entered URLs can interfere with HCP Terraform's operation. + + To check the hook URLs for a repository, go to the repository's settings, then go to the "Hooks" page (in the "Workflow" section) and click on the "Post-Receive WebHooks" link. + + Also note that some Bitbucket Data Center versions might allow you to set per-project or server-wide hook URLs in addition to per-repository hooks. These should all be empty; if you set a hook URL that might affect more than one repo when installing the plugin, go back and delete it. +- Make sure you aren't trying to connect too many workspaces to a single repository. Bitbucket Data Center's webhooks plugin can only attach five hooks to a given repo. You might need to create additional repositories if you need to make more than five workspaces from a single configuration repo. + +## Bitbucket Cloud + +### HCP Terraform fails to obtain repositories + +This typically happens when the HCP Terraform application in Bitbucket Cloud wasn't configured to have the full set of permissions. Go to the OAuth section of the Bitbucket settings, find your HCP Terraform OAuth consumer, click the edit link in the "..." menu, and ensure it has the required permissions enabled: + +| Permission type | Permission level | +| --------------- | ---------------- | +| Account | Write | +| Repositories | Admin | +| Pull requests | Write | +| Webhooks | Read and write | + +## GitHub + +### "Host key verification failed" error in `terraform init` when attempting to ingress Terraform modules via Git over SSH + +This is most common when running Terraform 0.10.3 or 0.10.4, which had a bug in handling SSH submodule ingress. Try upgrading affected HCP Terraform workspaces to the latest Terraform version or 0.10.8 (the latest in the 0.10 series). + +### HCP Terraform can't ingress Git submodules, with auth errors during init + +This usually happens when an SSH key isn't associated with the VCS provider's OAuth client. + +- Go to your organization's "VCS Provider" settings page and check your GitHub client. If it still says "You can add a private SSH key to this connection to be used for git clone operations" (instead of "A private SSH key has been added..."), you need to click the "add a private SSH key" link and add a key. +- Check the settings page for affected workspaces and ensure that "Include submodules on clone" is enabled. + +Note that the "SSH Key" section in a workspace's settings is only used for mid-run operations like cloning Terraform modules. It isn't used when cloning the linked repository before a run. + +## General + +The following errors may occur for all VCS providers except Bitbucket Data Center. + +### HCP Terraform returns 500 after authenticating with the VCS provider + +The Callback URL in the OAuth application configuration in the VCS provider probably wasn't updated in the last step of the instructions and still points to the default "/" path (or an example.com link) instead of the full callback url. + +The fix is to update the callback URL in your VCS provider's application settings. You can look up the real callback URL in HCP Terraform's settings. + +### Can't delete a workspace or module, resulting in 500 errors + +This often happens when the VCS connection has been somehow broken: it might have had permissions revoked, been reconfigured, or had the repository removed. Check for these possibilities and contact HashiCorp support for further assistance, including any information you collected in your support ticket. + +### `redirect_uri_mismatch` error on "Connect" + +The domain name for HCP Terraform's SaaS release changed on 02/22 at 9AM from `atlas.hashicorp.com` to `app.terraform.io`. If the OAuth client was originally configured on the old domain, using it for a new VCS connection can result in this error. + +The fix is to update the OAuth Callback URL in your VCS provider to use app.terraform.io instead of atlas.hashicorp.com. + +### Can't trigger workspace runs from VCS webhook + +A workspace with no runs will not accept new runs from a VCS webhook. You must queue at least one run manually. + +A workspace will not process a webhook if the workspace previously processed a webhook with the same commit SHA and created a run. To trigger a run, create a new commit. If a workspace receives a webhook with a previously processed commit, HCP Terraform adds a new event to the [VCS Events](/terraform/enterprise/vcs#viewing-events) page documenting the received webhook. + +### Changing the URL for a VCS provider + +On rare occasions, you might need HCP Terraform to change the URL it uses to reach your VCS provider. This usually only happens if you move your VCS server or the VCS vendor changes their supported API versions. + +HCP Terraform does not allow you to change the API URL for an existing VCS connection, but you can create a new VCS connection and update existing resources to use it. This is most efficient if you script the necessary updates using HCP Terraform's API. In brief: + +1. [Configure a new VCS connection](/terraform/enterprise/vcs) with the updated URL. +2. Obtain the [oauth-token IDs](/terraform/enterprise/api-docs/oauth-tokens) for the old and new OAuth clients. +3. [List all workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces) (dealing with pagination if necessary), and use a JSON filtering tool like `jq` to make a list of all workspace IDs whose `attributes.vcs-repo.oauth-token-id` matches the old VCS connection. +4. Iterate over the list of workspaces and [PATCH each one](/terraform/enterprise/api-docs/workspaces#update-a-workspace) to use the new `oauth-token-id`. +5. [List all registry modules](/terraform/registry/api-docs#list-modules) and use their `source` property to determine which ones came from the old VCS connection. +6. [Delete each affected module](/terraform/enterprise/api-docs/private-registry/modules#delete-a-module), then [create a new module](/terraform/enterprise/api-docs/private-registry/modules#publish-a-private-module-from-a-vcs) from the new connection's version of the relevant repo. +7. Delete the old VCS connection. + +### Reauthorizing VCS OAuth Providers + +If a VCS OAuth connection breaks, you can reauthorize an existing VCS provider while retaining any VCS connected resources, like workspaces. We recommend only using this feature to fix broken VCS connections. We also recommend reauthorizing using the same VCS account to avoid permission changes to your repositories. + +~> **Important:** Reauthorizing is not available when the [TFE Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/oauth_client) is managing the OAuth Client. Instead, you can update the [oauth_token](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/oauth_client#oauth_token) argument with a new token from your VCS Provider. + +To reauthorize a VCS connection, complete the following steps: + +1. Go to your organization's settings and click **Providers** under **Version Control**. +2. Click **Reauthorize** in the **OAuth Token ID** column. +3. Confirm the reauthorization. HCP Terraform redirects you to your VCS Provider where you can reauthorize the connection. + +## Certificate Errors on Terraform Enterprise + +When debugging failures of VCS connections due to certificate errors, running additional diagnostics using the OpenSSL command may provide more information about the failure. + +First, attach a bash session to the application container: + + docker exec -it ptfe_atlas sh -c "stty rows 50 && stty cols 150 && bash" + +Then run the `openssl s_client` command, using the certificate at `/tmp/cust-ca-certificates.crt` in the container: + + openssl s_client -showcerts -CAfile /tmp/cust-ca-certificates.crt -connect git-server-hostname:443 + +For example, a Gitlab server that uses a self-signed certificate might result in an error like `verify error:num=18:self signed certificate`, as shown in the output below: + + bash-4.3# openssl s_client -showcerts -CAfile /tmp/cust-ca-certificates.crt -connect gitlab.local:443 + CONNECTED(00000003) + depth=0 CN = gitlab.local + verify error:num=18:self signed certificate + verify return:1 + depth=0 CN = gitlab.local + verify return:1 + --- + Certificate chain + 0 s:/CN=gitlab.local + i:/CN=gitlab.local + -----BEGIN CERTIFICATE----- + MIIC/DCCAeSgAwIBAgIJAIhG2GWtcj7lMA0GCSqGSIb3DQEBCwUAMCAxHjAcBgNV + BAMMFWdpdGxhYi1sb2NhbC5oYXNoaS5jbzAeFw0xODA2MDQyMjAwMDhaFw0xOTA2 + MDQyMjAwMDhaMCAxHjAcBgNVBAMMFWdpdGxhYi1sb2NhbC5oYXNoaS5jbzCCASIw + DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMMgrpo3zsoy2BP/AoGIgrYwEMnj + PwSOFGNHbclmiVBCW9jvrZrtva8Qh+twU7CSQdkeSP34ZgLrRp1msmLvUuVMgPts + i7isrI5hug/IHLLOGO5xMvxOcrHknvySYJRmvYFriEBPNRPYJGJ9O1ZUVUYeNwW/ + l9eegBDpJrdsjGmFKCOzZEdUA3zu7PfNgf788uIi4UkVXZNa/OFHsZi63OYyfOc2 + Zm0/vRKOn17dewOOesHhw77yYbBH8OFsEiC10JCe5y3MD9yrhV1h9Z4niK8rHPXz + XEh3JfV+BBArodmDbvi4UtT+IGdDueUllXv7kbwqvQ67OFmmek0GZOY7ZvMCAwEA + AaM5MDcwIAYDVR0RBBkwF4IVZ2l0bGFiLWxvY2FsLmhhc2hpLmNvMBMGA1UdJQQM + MAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4IBAQCfkukNV/9vCA/8qoEbPt1M + mvf2FHyUD69p/Gq/04IhGty3sno4eVcwWEc5EvfNt8vv1FykFQ6zMJuWA0jL9x2s + LbC8yuRDnsAlukSBvyazCZ9pt3qseGOLskaVCeOqG3b+hJqikZihFUD95IvWNFQs + RpvGvnA/AH2Lqqeyk2ITtLYj1AcSB1hBSnG/0fdtao9zs0JQsrS59CD1lbbTPPRN + orbKtVTWF2JlJxl2watfCNTw6nTCPI+51CYd687T3MuRN7LsTgglzP4xazuNjbWB + QGAiQRd6aKj+xAJnqjzXt9wl6a493m8aNkyWrxZGHfIA1W70RtMqIC/554flZ4ia + -----END CERTIFICATE----- + --- + Server certificate + subject=/CN=gitlab.local + issuer=/CN=gitlab.local + --- + No client certificate CA names sent + Peer signing digest: SHA512 + Server Temp Key: ECDH, P-256, 256 bits + --- + SSL handshake has read 1443 bytes and written 433 bytes + --- + New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384 + Server public key is 2048 bit + Secure Renegotiation IS supported + Compression: NONE + Expansion: NONE + No ALPN negotiated + SSL-Session: + Protocol : TLSv1.2 + Cipher : ECDHE-RSA-AES256-GCM-SHA384 + Session-ID: AF5286FB7C7725D377B4A5F556DEB6DDC38B302153DDAE90C552ACB5DC4D86B8 + Session-ID-ctx: + Master-Key: DB75AEC12C6E7B62246C653C8CB8FC3B90DE86886D68CB09898A6A6F5D539007F7760BC25EC4563A893D34ABCFAAC28A + Key-Arg : None + PSK identity: None + PSK identity hint: None + SRP username: None + TLS session ticket lifetime hint: 300 (seconds) + TLS session ticket: + 0000 - 03 c1 35 c4 ff 6d 24 a8-6c 70 61 fb 2c dc 2e b8 ..5..m$.lpa.,... + 0010 - de 4c 6d b0 2c 13 8e b6-63 95 18 ee 4d 33 a6 dc .Lm.,...c...M3.. + 0020 - 0d 64 24 f0 8d 3f 9c aa-b8 a4 e2 4f d3 c3 4d 88 .d$..?.....O..M. + 0030 - 58 99 10 73 83 93 70 4a-2c 61 e7 2d 41 74 d3 e9 X..s..pJ,a.-At.. + 0040 - 83 8c 4a 7f ae 7b e8 56-5c 51 fc 6f fe e3 a0 ec ..J..{.V\Q.o.... + 0050 - 3c 2b 6b 13 fc a0 e5 15-a8 31 16 19 11 98 56 43 <+k......1....VC + 0060 - 16 86 c4 cd 53 e6 c3 61-e2 6c 1b 99 86 f5 a8 bd ....S..a.l...... + 0070 - 3c 49 c0 0a ce 81 a9 33-9b 95 2c e1 f4 6d 05 1e - + Best practices to structure your configuration and Terraform Enterprise + workspaces +source: terraform-docs-common +--- + +# Workspace Best Practices + +An HCP Terraform workspace manages a single state file and the lifecycle of its resources. It is the smallest collection of HCP Terraform-managed infrastructure. Any operation on a resource can potentially affect other resources managed in the same state file, so it is best to keep the potential blast radius of your operations small. To do so, manage resources in separate workspaces when possible, grouping together only necessary and logically-related resources. For example, even though your application may require both compute resources and a database, these resources can operate independently and should be in their own workspaces. +Scoping your configuration and planning your workspace strategy early in your adoption of HCP Terraform and Terraform Enterprise will simplify your operations and make them safer. + +## Name your Workspace + +We recommend using the following naming convention so you can identify and associate workspaces with specific components of your infrastructure: + +`---` + +- ``: The business unit or team that owns the workspace. +- ``: The name of the application or service that the workspace manages. +- ``: The layer of the infrastructure that the workspace manages (or example, network, compute, filestore). +- ``: The environment that the workspace manages (for example, prod, staging, QA, prod). + +If your application team does not have a `layer`, use `main` or `app` in its place to maintain consistency across the organization. + +## Group by volatility + +Volatility refers to the rate of change of the resources in a workspace. Infrastructure such as databases, VPCs, and subnets change much less frequently than infrastructure such as your web servers. By exposing your long-living infrastructure to unnecessary volatility, you introduce more opportunities for accidental changes. When planning your workspace organization, group resources by volatility. + +![An example of how workspaces can be split among Production, Staging, QA, and Dev. In this example, networking and security are grouped in one workspace, with compute, filestore, and SQL all having their own workspace. This is duplicated in each environment](/img/docs/workspace-net-infra-split.png) + +The above example groups together tightly-coupled resources like networking, security, and identity in a shared workspace. Compute, storage, and databases have separate workspaces, since they change at different frequencies. You may scale compute instances multiple times a day, but your database instances probably change far less frequently. By grouping these parts of your infrastructure into separate workspaces, you decouple unrelated resources and reduce the risk of unexpected changes. + +## Determine stateful vs stateless infrastructure + +Stateful resources are ones that you cannot delete and recreate because they persist data, such as databases and object storage. By managing stateful resources independently of stateless ones, such as separating databases from compute instances, you limit the blast radius of operations that cause the resource recreation and help protect against accidental data loss. + +Consider the workspace structure in the [Volatility section](#group-by-volatility). You could potentially manage filestore and database resources together, as they are both stateful resources. Your compute resources are stateless and should still have a separate workspace. + +## Separate privileges and responsibilities + +A best practice is to split up workspaces based on team responsibilities and required privileges. For example, consider an application that requires separate developer and production environments, each with special networking and application infrastructure. One approach is to create four different workspaces, two for the developer environment and two for production. Only the networking team has access to the networking workspaces. + +In this setup, only the networking team needs permissions to manage the resources in the networking workspaces, and others cannot manage those workspace resources. If a workspace's scope is too large, a user might need more permissions than appropriate in order to perform operations the workspace. + +![An example of how workspaces can be split among Production, Staging, QA, and Dev. In this example, networking and security are grouped in one workspace, with compute, filestore, and SQL all having their own workspace. This is duplicated in each environment](/img/docs/workspace-net-infra-combined.png) + +Splitting your workspaces by team also helps limit the responsibility per workspace and allows teams to maintain distinct areas of ownership. If you need to reference attributes of resources managed in other workspaces, you can share the outputs using the [tfe_outputs](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) data source. By limiting the scope of each workspace and sharing just the required outputs with others, you reduce the risk of leaking potentially sensitive information in a workspace's state. To share outputs from a workspace, you must explicitly enable remote state sharing in the workspace settings. + +## Avoid large Terraform plans and applies + +HCP Terraform and Terraform Enterprise execute workloads using agents. Every time an agent refreshes a workspace's state, it builds a [dependency graph](/terraform/internals/graph) of the resources to determine how to sequence operations in the workspace. As the number of resources your workspace manages grows, these graphs become larger and more complex. As these graphs grow, they require more worker RAM to build them. If your agent's performance degrades or workloads take longer to complete, we suggest exploring ways to split up the workspace to reduce the size of the dependency graph. + +## Determine workspace concurrency vs Terraform parallelism + +Concurrency refers to the number of plan and apply operations HCP Terraform or Terraform Enterprise can run simultaneously. In HCP Terraform, your subscription limits the maximum concurrency. Terraform Enterprise lets you configure the concurrency, but defaults to 10 concurrent runs. As you increase concurrency, the amount of memory your Terraform Enterprise installation requires increases as well. Refer to the [Capacity and performance](/terraform/enterprise/replicated/architecture/system-overview/capacity) documentation for more information. + +Parallelism refers to the number of tasks the Terraform CLI performs simultaneously in a single workload. By default, Terraform performs a maximum of 10 operations in parallel. When running a `terraform apply` command, Terraform refreshes each resource in the state file and compares to the remote object. Every resource refresh, creation, update, or destruction is an individual operation. If your workload creates 11 resources, Terraform starts by creating the first 10 resources in its dependency graph, and will begin creating the 11th once it finishes creating one of the first 10 resources. + +You can [increase the parallelism](/terraform/enterprise/workspaces/variables#parallelism) of Terraform, but this increases a run's CPU usage. We recommend that you instead break down large Terraform configurations into smaller ones with fewer resources when possible. Long-running Terraform workloads are an early sign of a bloated workspace scope. + +## Next steps + +This article introduces some considerations to keep in mind as your organization matures their workspace usage. Being deliberate about how you use these to organize your infrastructure will ensure smoother and safer operations. [HCP Terraform](/terraform/tutorials/cloud-get-started) provides a place to try these concepts hands-on, and you can [get started for free](https://app.terraform.io/public/signup/account). + +To learn more about HCP Terraform and Terraform Enterprise best practices, refer to [Project Best Practices](/terraform/enterprise/projects/best-practices). To learn best practices for writing Terraform configuration, refer to the [Terraform Style Guide](/terraform/language/style). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/browse.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/browse.mdx new file mode 100644 index 0000000000..3b7ef87d01 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/browse.mdx @@ -0,0 +1,72 @@ +--- +page_title: Browse workspaces +description: >- + Learn how to use the sorting and filtering interfaces in Terraform Enterprise + to create different views of the resource data that the app manages so that + you can track consumption across your organizations. +source: terraform-docs-common +--- + +# Browse workspaces + +This topic describes how to use browse, sort, and filter workspaces in the UI so that you can track consumption across your organizations. + +## Overview + +HCP Terraform and Terraform Enterprise include several interfaces for browsing, sorting, and filtering resource data so that you can effectively manage workspaces and projects. You can also use interfaces together, such as applying a tag filter and sorting by workspace name, to refine results. + + + +### Explorer view + +The explorer for workspace visibility surfaces a wider range of valuable information from across your workspaces. Refer to [Explorer for workspace visibility](/terraform/enterprise/workspaces/explorer) for additional information. + + + +## Requirements + +You must be a member of a team with the **Read** permissions enabled for Terraform runs to view workspaces associated with the run. Refer to the [permissions reference](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +If your organization contains many workspaces, you can use the filter tools at the top of the list to find the workspaces you are interested in. + +## Find a workspace + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select your organization. +2. Click **Workspaces** to view workspaces you have access to. +3. To view projects you have access to, click on either **Projects** in the sidebar menu or the drawer icon in the **Workspaces** bar. +4. If your organization contains several workspaces or projects, you can paginate through the workspace screen or project drawer to find the workspace you are looking for. +5. You can also use the search bar in the **Workspace** drawer to find a project by name + +## Filter workspaces + +You can use the following interfaces to sort and filter workspaces: + +- Click on a run status button to filter workspaces by one of the most common run statuses. You can filter by one of the following statuses: + + - Needs attention + - Errored + - Running + - On hold + - Applied + +- Choose one or more tag keys, values, or key-value pairs from the **Tags** drop-down to filter workspaces by tag. + +- Choose one or more run statuses from the **Status** drop-down to filter workspaces by run status. The **Status** drop-down lists all available run statuses, including the common statuses available in the run status button bar. + +- The tag filter shows a list of tags added to all workspaces, limited to the first 1,000 tags alphabetically. Choosing one or more will show only workspaces tagged with all of the chosen tags. + +- Choose a health assessment label form the **Health** drop-down to filter workspaces according to the latest health assessment results. You can filter according to the following labels: + + - Drifted + - Health error + - Check failed + +## Sort workspaces + +Click on a column header to sort workspaces by trait. Traits appear in either ascending or descending alphabetical order. You can sort according to the following traits: + +- Workspace name +- Run status +- Repository +- Latest change +- Tag diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/configurations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/configurations.mdx new file mode 100644 index 0000000000..f56346f09b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/configurations.mdx @@ -0,0 +1,73 @@ +--- +page_title: Manage Terraform configurations +description: >- + Workspaces organize infrastructure and state. Learn how to provide + configuration versions for a workspace and organize multiple environments. +source: terraform-docs-common +--- + +# Manage Terraform configurations + +[remote operations]: /terraform/enterprise/run/remote-operations + +[execution mode]: /terraform/enterprise/workspaces/settings#execution-mode + +[Terraform configuration]: /terraform/language + +Each HCP Terraform workspace is associated with a particular [Terraform configuration][], which is expected to change and evolve over time. + +Since every organization has its own preferred source code control practices, HCP Terraform does not provide integrated version management. Instead, it expects Terraform configurations to be managed in your existing version control system (VCS). + +In order to perform [remote Terraform runs][remote operations] for a given workspace, HCP Terraform needs to periodically receive new versions of its configuration. Usually, this can be handled automatically by connecting a workspace to a VCS repository. + +-> **Note:** If a workspace's [execution mode is set to local][execution mode], it doesn't require configuration versions, since HCP Terraform won't perform runs for that workspace. + +## Providing Configuration Versions + +There are two ways to provide configuration versions for a workspace: + +- **With a connected VCS repository.** HCP Terraform can automatically fetch content from supported VCS providers, and uses webhooks to get notified of code changes. This is the most convenient way to use HCP Terraform. See [The UI- and VCS-driven Run Workflow](/terraform/enterprise/run/ui) for more information. + + A VCS connection can be configured [when a workspace is created](/terraform/enterprise/workspaces/create), or later in its [version control settings](/terraform/enterprise/workspaces/settings/vcs). + + -> **Note:** When a workspace is connected to a VCS repository, directly uploaded configuration versions can only be used for [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). This helps ensure your VCS remains the source of truth for all real infrastructure changes. + +- **With direct uploads.** You can use a variety of tools to directly upload configuration content to HCP Terraform: + + - **Terraform CLI:** With the [CLI integration](/terraform/cli/cloud) configured, the `terraform plan` and `terraform apply` commands will perform remote runs by uploading a configuration from a local working directory. See [The CLI-driven Run Workflow](/terraform/enterprise/run/cli) for more information. + - **API:** HCP Terraform's API can accept configurations as `.tar.gz` files, which can be uploaded by a CI system or other workflow tools. See [The API-driven Run Workflow](/terraform/enterprise/run/api) for more information. + + When configuration versions are provided via the CLI or API, HCP Terraform can't automatically react to code changes in the underlying VCS repository. + +## Code Organization and Repository Structure + +### Organizing Separate Configurations + +Most organizations either keep each Terraform configuration in a separate repository, or keep many Terraform configurations as separate directories in a single repository (often called a "monorepo"). + +HCP Terraform works well with either approach, but monorepos require some extra configuration: + +- Each workspace must [specify a Terraform working directory](/terraform/enterprise/workspaces/settings#terraform-working-directory), so HCP Terraform knows which configuration to use. +- If the repository includes any shared Terraform modules, you must add those directories to the [automatic run triggering setting](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering) for any workspace that uses those modules. + +-> **Note:** If your organization does not have a strong preference, we recommend using separate repositories for each configuration and using the private module registry to share modules. This allows for faster module development, since you don't have to update every configuration that consumes a module at the same time as the module itself. + +### Organizing Multiple Environments for a Configuration + +There are also a variety of ways to handle multiple environments. The most common approaches are: + +- All environments use the same main branch, and environment differences are handled with Terraform variables. To protect production environments, wait to apply runs until their changes are verified in staging. +- Different environments use different long-lived VCS branches. To protect production environments, merge changes to the production branch after they have been verified in staging. +- Different environments use completely separate configurations, and shared behaviors are handled with shared Terraform modules. To protect production environments, verify new module versions in staging before updating the version used in production. + +HCP Terraform works well with all of these approaches. If you used long-lived branches, be sure to specify which branch to use in each workspace's VCS connection settings. + +## Archiving Configuration Versions + +Once all runs using a particular configuration version are complete, HCP Terraform no longer needs the associated `.tar.gz` file and may discard it to save storage space. This process is handled differently depending on how the configuration version was created. + +- **Created with a connected VCS repository.** HCP Terraform will automatically archive VCS configuration versions once all runs are completed and they are no longer current for any workspace. HCP Terraform will re-fetch the configuration files from VCS as needed for new runs. + +- **Created with direct uploads via the API or CLI.** HCP Terraform does not archive CLI and API configuration versions automatically, because it cannot re-fetch the files for new runs. However, you can use the [Archive a Configuration Version](/terraform/enterprise/api-docs/configuration-versions#archive-a-configuration-version) endpoint to archive them manually. + +For Terraform Enterprise customers upgrading from a previous version, the functionality has a backfill capability that will clean up space for historical runs in batches. In each organization, Terraform Enterprise archives a batch of 100 configurations each time a run completes or a new configuration version is uploaded. This will gradually free up existing object storage space over time. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/create.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/create.mdx new file mode 100644 index 0000000000..e52c6468b2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/create.mdx @@ -0,0 +1,110 @@ +--- +page_title: Create workspaces in Terraform Enterprise +description: >- + Workspaces organize infrastructure and state into groups. Learn how to create + and configure Terraform Enterprise workspaces through the UI. +source: terraform-docs-common +--- + +# Create workspaces + +This topic describes how to create and manage workspaces in HCP Terraform and Terraform Enterprise UI. A workspace is a group of infrastructure resources managed by Terraform. Refer to [Workspaces overview](/terraform/enterprise/workspaces) for additional information. + +> **Hands-on:** Try the [Get Started - HCP Terraform](/terraform/tutorials/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. + +## Introduction + +Create new workspaces when you need to manage a new collection of infrastructure resources. You can use the following methods to create workspaces: + +- HCP Terraform UI: Refer to [Create a workspace](#create-a-workspace) for instructions. +- Workspaces API: Send a `POST`call to the `/organizations/:organization_name/workspaces` endpoint to create a workspace. Refer to the [API documentation](/terraform/enterprise/api-docs/workspaces#create-a-workspace) for instructions. +- Terraform Enterprise provider: Install the `tfe` provider and add the `tfe_workspace` resource to your configuration. Refer to the [`tfe` provider documentation](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/workspace) in the Terraform registry for instructions. +- No-code provisioning: Use a no-code module from the registry to create a new workspace and deploy the module's resources. Refer to [Provisioning No-Code Infrastructure](/terraform/enterprise/no-code-provisioning/provisioning) for instructions. + +Each workspace belongs to a project. Refer to [Manage projects](/terraform/enterprise/projects/manage) for additional information. + +## Requirements + +You must be a member of a team with one of the following permissions enabled to create and manage workspaces: + +- **Manage all projects** +- **Manage all workspaces** +- **Admin** permission group for a project. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Workspace naming + +We recommend using consistent and informative names for new workspaces. One common approach is combining the workspace's important attributes in a consistent order. Attributes can be any defining characteristic of a workspace, such as the component, the component’s run environment, and the region where the workspace is provisioning infrastructure. + +This strategy could produce the following example workspace names: + +- networking-prod-us-east +- networking-staging-us-east +- networking-prod-eu-central +- networking-staging-eu-central +- monitoring-prod-us-east +- monitoring-staging-us-east +- monitoring-prod-eu-central +- monitoring-staging-eu-central + +You can add additional attributes to your workspace names as needed. For example, you may add the infrastructure provider, datacenter, or line of business. + +We recommend using 90 characters or less for the name of your workspace. + +## Create a workspace + +[workdir]: /terraform/enterprise/workspaces/settings#terraform-working-directory + +[trigger]: /terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering + +[branch]: /terraform/enterprise/workspaces/settings/vcs#vcs-branch + +[submodules]: /terraform/enterprise/workspaces/settings/vcs#include-submodules-on-clone + +Complete the following steps to use the HCP Terraform or Terraform Enterprise UI to create a workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and choose your organization. +2. Click **New** and choose **Workspace** from the drop-down menu. +3. If you have multiple projects, HCP Terraform may prompt you to choose the project to create the workspace in. Only users on teams with permissions for the entire project or the specific workspace can access the workspace. Refer to [Manage projects](/terraform/enterprise/projects/manage) for additional information. +4. Choose a workflow type. +5. Complete the following steps if you are creating a workspace that follows the VCS workflow: + 1. Choose an existing version control provider from the list or configure a new system. You must enable the workspace project to connect to your provider. Refer to [Connecting VCS + Providers](/terraform/enterprise/vcs) for more details. + 2. If you choose the **GitHub App** provider, choose an organization and repository when prompted. The list only displays the first 100 repositories from your VCS provider. If your repository is missing from the list, enter the repository ID in the text field . + 3. Refer to the following topics for information about configuring workspaces settings in the **Advanced options** screen: + - [Terraform Working Directory][workdir] + - [Automatic Run Triggering][trigger] + - [VCS branch][branch] + - [Include submodules on clone][submodules] +6. Specify a name for the workspace. VCS workflow workspaces default to the name of the repository. The name must be unique within the organization and can include letters, numbers, hyphens, and underscores. Refer to [Workspace naming](#workspace-naming) for additional information. +7. Add an optional description for the workspace. The description appears at the top of the workspace in the HCP Terraform UI. +8. Click **Create workspace** to finish. + +For CLI or API-driven workflow, the system opens the new workspace overview. For version control workspaces, the **Configure Terraform variables** page appears. + +### Configure Terraform variables for VCS workflows + +After you create a new workspace from a version control repository, HCP Terraform scans its configuration files for [Terraform variables](/terraform/enterprise/workspaces/variables#terraform-variables) and displays variables without default values or variables that are undefined in an existing [global or project-scoped variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). Terraform cannot perform successful runs in the workspace until you set values for these variables. + +Choose one of the following actions: + +- To skip this step, click **Go to workspace overview**. You can [load these variables from files](/terraform/enterprise/workspaces/variables/managing-variables#loading-variables-from-files) or create and set values for them later from within the workspace. HCP Terraform does not automatically scan your configuration again; you can only add variables from within the workspace individually. +- To configure variables, enter a value for each variable on the page. You may want to leave a variable empty if you plan to provide it through another source, like an `auto.tfvars` file. Click **Save variables** to add these variables to the workspace. + +## Next steps + +If you have already configured all Terraform variables, we recommend [manually starting a run](/terraform/enterprise/run/ui#manually-starting-runs) to prepare VCS-driven workspaces. You may also want to do one or more of the following actions: + +- [Upload configuration versions](/terraform/enterprise/workspaces/configurations#providing-configuration-versions): If you chose the API or CLI-Driven workflow, you must upload configuration versions for the workspace. +- [Edit environment variables](/terraform/enterprise/workspaces/variables): Shell environment variables store credentials and customize Terraform's behavior. +- [Edit additional workspace settings](/terraform/enterprise/workspaces/settings): This includes notifications, permissions, and run triggers to start runs automatically. +- [Learn more about running Terraform in your workspace](/terraform/enterprise/run/remote-operations): This includes how Terraform processes runs within the workspace, run modes, run states, and other operations. +- [Create workspace tags](/terraform/enterprise/workspaces/tags): Add tags to your workspaces so that you can organize and track them. +- [Browse workspaces](/terraform/enterprise/workspaces/browse): Use the interfaces available in the UI to browse, sort, and filter workspaces so that you can track resource consumption. + +### VCS Connection + +If you connected a VCS repository to the workspace, HCP Terraform automatically registers a webhook with your VCS provider. A workspace with no runs will not accept new runs from a VCS webhook, so you must [manually start at least one run](/terraform/enterprise/run/ui#manually-starting-runs). + +After you manually start a run, HCP Terraform automatically queues a plan when new commits appear in the selected branch of the linked repository or someone opens a pull request on that branch. Refer to [Webhooks](/terraform/enterprise/vcs#webhooks) for more details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/aws-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/aws-configuration.mdx new file mode 100644 index 0000000000..3d84e52e56 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/aws-configuration.mdx @@ -0,0 +1,165 @@ +--- +page_title: Use dynamic credentials with the AWS provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the AWS Terraform + provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the AWS provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with AWS to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the AWS provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure AWS](#configure-aws):** Set up a trust configuration between AWS and HCP Terraform. Then, you must create AWS roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to AWS during each run. The AWS provider authentication is valid for the length of the plan or apply. + +## Configure AWS + +You must enable and configure an OIDC identity provider and accompanying role and trust policy on AWS. These instructions use the AWS console, but you can also use Terraform to configure AWS. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/aws). + +### Create an OIDC Identity Provider + +AWS documentation for setting this up through the AWS console or API can be found here: [Creating OpenID Connect (OIDC) identity providers - AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). + +The `provider URL` should be set to the address of HCP Terraform (e.g., **without** a trailing slash), and the `audience` should be set to `aws.workload.identity` or the value of `TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE`, if configured. + +### Configure a Role and Trust Policy + +You must configure a role and corresponding trust policy. Amazon documentation on setting this up can be found here: [Creating a role for web identity or OpenID Connect Federation (console) - AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html). +The trust policy will be of the form: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "OIDC_PROVIDER_ARN" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "SITE_ADDRESS:aud": "AUDIENCE_VALUE", + "SITE_ADDRESS:sub": "organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:RUN_PHASE" + } + } + } + ] +} +``` + +with the capitalized values replaced with the following: + +- **OIDC_PROVIDER_ARN**: The ARN from the OIDC provider resource created in the previous step +- **SITE_ADDRESS**: The address of HCP Terraform with `https://` stripped, (e.g., `app.terraform.io`) +- **AUDIENCE_VALUE**: This should be set to `aws.workload.identity` unless a non-default audience has been specified in TFC +- **ORG_NAME**: The organization name this policy will apply to, such as `my-org-name` +- **PROJECT_NAME**: The project name that this policy will apply to, such as `my-project-name` +- **WORKSPACE_NAME**: The workspace name this policy will apply to, such as `my-workspace-name` +- **RUN_PHASE**: The run phase this policy will apply to, currently one of `plan` or `apply`. + +-> **Note:** if different permissions are desired for plan and apply, then two separate roles and trust policies must be created for each of these run phases to properly match them to the correct access level. +If the same permissions will be used regardless of run phase, then the condition can be modified like the below to use `StringLike` instead of `StringEquals` for the sub and include a `*` after `run_phase:` to perform a wildcard match: + +```json +{ + "Condition": { + "StringEquals": { + "SITE_ADDRESS:aud": "AUDIENCE_VALUE" + }, + "StringLike": { + "SITE_ADDRESS:sub": "organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:*" + } + } +} +``` + +!> **Warning**: you should always check, at minimum, the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations! + +A permissions policy needs to be added to the role which defines what operations within AWS the role is allowed to perform. As an example, the below policy allows for fetching a list of S3 buckets: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": "*" + } + ] +} +``` + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with AWS using dynamic credentials. You can set these as workspace variables, or if you’d like to share one AWS role across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AWS_PROVIDER_AUTH`
`TFC_AWS_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to AWS. | +| `TFC_AWS_RUN_ROLE_ARN`
`TFC_AWS_RUN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_AWS_RUN_ROLE_ARN` | The ARN of the role to assume in AWS. | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_AWS_PLAN_ROLE_ARN` and `TFC_AWS_APPLY_ROLE_ARN` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/aws-configuration#optional-environment-variables) | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_AWS_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to `aws.workload.identity`. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_AWS_PLAN_ROLE_ARN`
`TFC_AWS_PLAN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_AWS_PLAN_ROLE_ARN` | The ARN of the role to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AWS_RUN_ROLE_ARN` if not provided. | +| `TFC_AWS_APPLY_ROLE_ARN`
`TFC_AWS_APPLY_ROLE_ARN[_TAG]`
`TFC_DEFAULT_AWS_APPLY_ROLE_ARN` | The ARN of the role to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AWS_RUN_ROLE_ARN` if not provided. | + +## Configure the AWS Provider + +Make sure that you’re passing a value for the `region` argument into the provider configuration block or setting the `AWS_REGION` variable in your workspace. + +Make sure that you’re not using any of the other arguments or methods mentioned in the [authentication and configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration) section of the provider documentation as these settings may interfere with dynamic provider credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct AWS setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_aws_dynamic_credentials" { + description = "Object containing AWS dynamic credentials configuration" + type = object({ + default = object({ + shared_config_file = string + }) + aliases = map(object({ + shared_config_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "aws" { + shared_config_files = [var.tfc_aws_dynamic_credentials.default.shared_config_file] +} + +provider "aws" { + alias = "ALIAS1" + shared_config_files = [var.tfc_aws_dynamic_credentials.aliases["ALIAS1"].shared_config_file] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/azure-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/azure-configuration.mdx new file mode 100644 index 0000000000..502cd60c8d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/azure-configuration.mdx @@ -0,0 +1,177 @@ +--- +page_title: Use dynamic credentials with the Azure provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the Azure Terraform + providers in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the Azure provider + +~> **Important:** Ensure you are using version **3.25.0** or later of the **AzureRM provider** and version **2.29.0** or later of the **Microsoft Entra ID provider** (previously Azure Active Directory) as required OIDC functionality was introduced in these provider versions. + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Azure to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the AzureRM or Microsoft Entra ID providers in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Azure](#configure-azure):** Set up a trust configuration between Azure and HCP Terraform. Then, you must create Azure roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to Azure during each run. The Azure provider authentication is valid for the length of the plan or apply. + +!> **Warning:** Dynamic credentials with the Azure providers do not work when your Terraform Enterprise instance uses a custom or self-signed certificate. This limitation is due to restrictions in Azure. + +## Configure Azure + +You must enable and configure an application and service principal with accompanying federated credentials and permissions on Azure. These instructions use the Azure portal, but you can also use Terraform to configure Azure. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/azure). + +### Create an Application and Service Principal + +Follow the steps mentioned in the AzureRM provider docs here: [Creating the Application and Service Principal](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc#creating-the-application-and-service-principal). + +As mentioned in the documentation it will be important to make note of the `client_id` for the application as you will use this later for authentication. + +-> **Note:** you will want to skip the `“Configure Microsoft Entra ID Application to Trust a GitHub Repository”` section as this does not apply here. + +### Grant the Application Access to Manage Resources in Your Azure Subscription + +You must now give the created Application permission to modify resources within your Subscription. + +Follow the steps mentioned in the AzureRM provider docs here: [Granting the Application access to manage resources in your Azure Subscription](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc#granting-the-application-access-to-manage-resources-in-your-azure-subscription). + +### Configure Microsoft Entra ID Application to Trust a Generic Issuer + +Finally, you must create federated identity credentials which validate the contents of the token sent to Azure from HCP Terraform. + +Follow the steps mentioned in the AzureRM provider docs here: [Configure Azure Microsoft Entra ID Application to Trust a Generic Issuer](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc#configure-azure-active-directory-application-to-trust-a-generic-issuer). + +The following information should be specified: + +- **Federated credential scenario**: Must be set to `Other issuer`. +- **Issuer**: The address of HCP Terraform (e.g., ). + - **Important**: make sure this value starts with **https://** and does _not_ have a trailing slash. +- **Subject identifier**: The subject identifier from HCP Terraform that this credential will match. This will be in the form `organization:my-org-name:project:my-project-name:workspace:my-workspace-name:run_phase:plan` where the `run_phase` can be one of `plan` or `apply`. +- **Name**: A name for the federated credential, such as `tfc-plan-credential`. Note that this cannot be changed later. + +The following is optional, but may be desired: + +- **Audience**: Enter the audience value that will be set when requesting the identity token. This will be `api://AzureADTokenExchange` by default. This should be set to the value of `TFC_AZURE_WORKLOAD_IDENTITY_AUDIENCE` if this has been configured. + +-> **Note:** because the `Subject identifier` for federated credentials is a direct string match, two federated identity credentials need to be created for each workspace using dynamic credentials: one that matches `run_phase:plan` and one that matches `run_phase:apply`. + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with Azure using dynamic credentials. You can set these as workspace variables. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AZURE_PROVIDER_AUTH`
`TFC_AZURE_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to Azure. | +| `TFC_AZURE_RUN_CLIENT_ID`
`TFC_AZURE_RUN_CLIENT_ID[_TAG]`
`TFC_DEFAULT_AZURE_RUN_CLIENT_ID` | The client ID for the Service Principal / Application used when authenticating to Azure. | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_AZURE_PLAN_CLIENT_ID` and `TFC_AZURE_APPLY_CLIENT_ID` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/azure-configuration#optional-environment-variables) | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AZURE_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_AZURE_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_AZURE_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to `api://AzureADTokenExchange`. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_AZURE_PLAN_CLIENT_ID`
`TFC_AZURE_PLAN_CLIENT_ID[_TAG]`
`TFC_DEFAULT_AZURE_PLAN_CLIENT_ID` | The client ID for the Service Principal / Application to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AZURE_RUN_CLIENT_ID` if not provided. | +| `TFC_AZURE_APPLY_CLIENT_ID`
`TFC_AZURE_APPLY_CLIENT_ID[_TAG]`
`TFC_DEFAULT_AZURE_APPLY_CLIENT_ID` | The client ID for the Service Principal / Application to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AZURE_RUN_CLIENT_ID` if not provided. | + +## Configure the AzureRM or Microsoft Entra ID Provider + +Make sure that you’re passing values for the `subscription_id` and `tenant_id` arguments into the provider configuration block or setting the `ARM_SUBSCRIPTION_ID` and `ARM_TENANT_ID` variables in your workspace. + +Make sure that you’re _not_ setting values for `client_id`, `use_oidc`, or `oidc_token` in the provider or setting any of `ARM_CLIENT_ID`, `ARM_USE_OIDC`, `ARM_OIDC_TOKEN`. + +### Specifying Multiple Configurations + +~> **Important:** Ensure you are using version **3.60.0** or later of the **AzureRM provider** and version **2.43.0** or later of the **Microsoft Entra ID provider** as required functionality was introduced in these provider versions. + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Azure setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_azure_dynamic_credentials" { + description = "Object containing Azure dynamic credentials configuration" + type = object({ + default = object({ + client_id_file_path = string + oidc_token_file_path = string + }) + aliases = map(object({ + client_id_file_path = string + oidc_token_file_path = string + })) + }) +} +``` + +#### Example Usage + +##### AzureRM Provider + +```hcl +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + client_id_file_path = var.tfc_azure_dynamic_credentials.default.client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.default.oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + alias = "ALIAS1" + client_id_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` + +##### Microsoft Entra ID Provider (formerly Azure AD) + +```hcl +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + client_id_file_path = var.tfc_azure_dynamic_credentials.default.client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.default.oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + alias = "ALIAS1" + client_id_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration.mdx new file mode 100644 index 0000000000..400f5e996f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration.mdx @@ -0,0 +1,174 @@ +--- +page_title: Use dynamic credentials with the GCP provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the GCP Terraform + provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the GCP provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with GCP to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure GCP](#configure-gcp):** Set up a trust configuration between GCP and HCP Terraform. Then, you must create GCP roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to GCP during each run. The GCP provider authentication is valid for the length of the plan or apply. + +!> **Warning:** Dynamic credentials with the GCP provider do not work if your Terraform Enterprise instance uses a custom or self-signed certificate. This limitation is due to restrictions in GCP. + +## Configure GCP + +You must enable and configure a workload identity pool and provider on GCP. These instructions use the GCP console, but you can also use Terraform to configure GCP. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/gcp). + +### Add a Workload Identity Pool and Provider + +Google documentation for setting this up can be found here: [Configuring workload identity federation with other identity providers](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers). + +Before starting to create the resources, you must enable the APIs mentioned at the start of the [Configure workload Identity federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#configure). + +#### Add a Workload Identity Pool + +The following information should be specified: + +- **Name**: Name for the pool, such as `my-tfc-pool`. The name is also used as the pool ID. You can't change the pool ID later. + +The following is optional, but may be desired: + +- **Pool ID**: The ID for the pool. This defaults to the name as mentioned above, but can be set to another value. +- **Description**: Text that describes the purpose of the pool. + +You will also want to ensure that the `Enabled Pool` option is set to be enabled before clicking next. + +#### Add a Workload Identity Provider + +You must add a workload identity provider to the pool. The following information should be specified: + +- **Provider type**: Must be `OpenID Connect (OIDC)`. +- **Provider name**: Name for the identity provider, such as `my-tfc-provider`. The name is also used as the provider ID. You can’t change the provider ID later. +- **Issuer (URL)**: The address of the TFC/E instance, such as + - **Important**: make sure this value starts with **https://** and does _not_ have a trailing slash. +- **Audiences**: This can be left as `Default audience` if you are planning on using the default audience HCP Terraform provides. + - **Important**: you must select the `Allowed audiences` toggle and set this to the value of `TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE`, if configured. +- **Provider attributes mapping**: At the minimum this must include `assertion.sub` for the `google.subject` entry. Other mappings can be added for other claims in the identity token to attributes by adding `attribute.[claim name]` on the Google side and `assertion.[claim name]` on the OIDC side of a new mapping. +- **Attribute Conditions**: Conditions to restrict which identity tokens can authenticate using the workload identity pool, such as `assertion.sub.startsWith("organization:my-org:project:my-project:workspace:my-workspace")` to restrict access to identity tokens from a specific workspace. See this page in Google documentation for more information on the expression language: [Attribute conditions](https://cloud.google.com/iam/docs/workload-identity-federation#conditions). + +!> **Warning**: you should always check, at minimum, the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations! + +The following is optional, but may be desired: + +- **Provider ID**: The ID for the provider. This defaults to the name as mentioned above, but can be set to another value. + +### Add a Service Account and Permissions + +You must next add a service account and properly configure the permissions. + +#### Create a Service Account + +Google documentation for setting this up can be found here: [Creating a service account for the external workload](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create_a_service_account_for_the_external_workload). + +The following information should be specified: + +- **Service account name**: Name for the service account, such as `tfc-service-account`. The name is also used as the pool ID. You can't change the pool ID later. + +The following is optional, but may be desired: + +- **Service account ID**: The ID for the service account. This defaults to the name as mentioned above, but can be set to another value. +- **Description**: Text that describes the purpose of the service account. + +#### Grant IAM Permissions + +The next step in the setup wizard will allow for granting IAM permissions for the service account. The role that is given to the service account will vary depending on your specific needs and project setup. This should in general be the most minimal set of permissions needed for the service account to properly function. + +#### Grant External Permissions + +Once the service account has been created and granted IAM permissions, you will need to grant access to the service account for the identity pool created above. Google documentation for setting this up can be found here: [Allow the external workload to impersonate the service account](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#allow_the_external_workload_to_impersonate_the_service_account). + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with GCP using dynamic credentials. You can set these as workspace variables, or if you’d like to share one GCP service account across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_GCP_PROVIDER_AUTH`
`TFC_GCP_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to use dynamic credentials to authenticate to GCP. | +| `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_RUN_SERVICE_ACCOUNT_EMAIL` | The service account email HCP Terraform will use when authenticating to GCP. | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL` and `TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration#optional-environment-variables) | + +You must also include information about the GCP Workload Identity Provider that HCP Terraform will use when authenticating to GCP. You can supply this information in two different ways: + +1. By providing one unified variable containing the canonical name of the workload identity provider. +2. By providing the project number, pool ID, and provider ID as separate variables. + +You should avoid setting both types of variables, but if you do, the unified version will take precedence. + +#### Unified Variable + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_GCP_WORKLOAD_PROVIDER_NAME`
`TFC_GCP_WORKLOAD_PROVIDER_NAME[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_PROVIDER_NAME` | The canonical name of the workload identity provider. This must be in the form mentioned for the `name` attribute [here](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/iam_workload_identity_pool_provider#attributes-reference) | Requires **v1.7.0** or later if self-managing agents. This will take precedence over `TFC_GCP_PROJECT_NUMBER`, `TFC_GCP_WORKLOAD_POOL_ID`, and `TFC_GCP_WORKLOAD_PROVIDER_ID` if set. | + +#### Separate Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `TFC_GCP_PROJECT_NUMBER`
`TFC_GCP_PROJECT_NUMBER[_TAG]`
`TFC_DEFAULT_GCP_PROJECT_NUMBER` | The project number where the pool and other resources live. | Requires **v1.7.0** or later if self-managing agents. This is _not_ the project ID and is a separate number. | +| `TFC_GCP_WORKLOAD_POOL_ID`
`TFC_GCP_WORKLOAD_POOL_ID[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_POOL_ID` | The workload pool ID. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_GCP_WORKLOAD_PROVIDER_ID`
`TFC_GCP_WORKLOAD_PROVIDER_ID[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_PROVIDER_ID` | The workload identity provider ID. | Requires **v1.7.0** or later if self-managing agents. | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to a string of the form mentioned [here](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#oidc_1) in the GCP docs with the leading **https:** stripped. | Requires **v1.7.0** or later if self-managing agents. This is one of the default `aud` formats that GCP accepts. | +| `TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_PLAN_SERVICE_ACCOUNT_EMAIL` | The service account email to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL` if not provided. | +| `TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_APPLY_SERVICE_ACCOUNT_EMAIL` | The service account email to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL` if not provided. | + +## Configure the GCP Provider + +Make sure that you’re passing values for the `project` and `region` arguments into the provider configuration block. + +Make sure that you’re not setting values for the `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` environment variables as these will conflict with the dynamic credentials authentication process. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_gcp_dynamic_credentials" { + description = "Object containing GCP dynamic credentials configuration" + type = object({ + default = object({ + credentials = string + }) + aliases = map(object({ + credentials = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "google" { + credentials = var.tfc_gcp_dynamic_credentials.default.credentials +} + +provider "google" { + alias = "ALIAS1" + credentials = var.tfc_gcp_dynamic_credentials.aliases["ALIAS1"].credentials +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration.mdx new file mode 100644 index 0000000000..2414f1b7af --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration.mdx @@ -0,0 +1,116 @@ +--- +page_title: Dynamic Credentials with the HCP Provider - Workspaces - Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the HCP provider in your + Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Dynamic Credentials with the HCP Provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.15.1](/terraform/cloud-docs/agents/changelog#1-15-1-05-01-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with HCP to authenticate with the HCP provider using [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) in your HCP Terraform runs. Configuring dynamic credentials for the HCP provider requires the following steps: + +1. **[Configure HCP](#configure-hcp):** Set up a trust configuration between HCP and HCP Terraform. Then, you must create a [service principal in HPC](https://developer.hashicorp.com/hcp/docs/hcp/admin/iam/service-principals) for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to HCP during each run. + +## Configure HCP + +You must enable and configure a workload identity pool and provider on HCP. These instructions use the HCP CLI, but you can also use Terraform to configure HCP. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/hcp). + +#### Create a Service Principal + +Create a service principal for HCP Terraform to assume during runs by running the following HCP command. Note the ID of the service principal you create because you will need it in the following steps. For all remaining steps, replace `HCP_PROJECT_ID` with the ID of the project that contains all the resources and workspaces that you want to manage with this service principal. If you wish to manage more than one project with dynamic credentials, it is recommended that you create multiple service principals, one for each project. + +```shell +hcp iam service-principals create hcp-terraform --project=HCP_PROJECT_ID +``` + +Grant your service principal the necessary permissions to manage your infrastructure during runs. + +```shell +hcp projects iam add-binding \ + --project=HCP_PROJECT_ID \ + --member=HCP_PRINCIPAL_ID \ + --role=roles/contributor +``` + +#### Add a Workload Identity Provider + +Next, create a workload identity provider that HCP uses to authenticate the HCP Terraform run. Make sure to replace `HCP_PROJECT_ID`, `ORG_NAME`, `PROJECT_NAME`, and `WORKSPACE_NAME` with their respective values before running the command. + +```shell +hcp iam workload-identity-providers create-oidc hcp-terraform-dynamic-credentials \ + --service-principal=iam/project/HCP_PROJECT_ID/service-principal/hcp-terraform \ + --issuer=https://app.terraform.io \ + --allowed-audience=hcp.workload.identity \ + --conditional-access='jwt_claims.sub matches `^organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:.*`' \ + --description="Allow HCP Terraform agents to act as the hcp-terraform service principal" +``` + +## Configure HCP Terraform + +Next, you need to set environment variables in your HCP Terraform workspace to configure HCP Terraform to authenticate with HCP using dynamic credentials. You can set these as workspace variables or use a variable set to share one HCP service principal across multiple workspaces. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HCP_PROVIDER_AUTH`
`TFC_HCP_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.15.1** or later if you use self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to use dynamic credentials to authenticate to HCP. | +| `TFC_HCP_RUN_PROVIDER_RESOURCE_NAME`
`TFC_HCP_RUN_PROVIDER_RESOURCE_NAME[_TAG]`
`TFC_DEFAULT_HCP_RUN_PROVIDER_RESOURCE_NAME` | The resource name of the workload identity provider that will be used to assume the service principal | Requires **v1.15.1** or later if you use self-managing agents. Optional if you provide `PLAN_PROVIDER_RESOURCE_NAME` and `APPLY_PROVIDER_RESOURCE_NAME`. [Learn more](#optional-environment-variables). | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HCP_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_HCP_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_HCP_WORKLOAD_IDENTITY_AUDIENCE` | HCP Terraform uses this as the `aud` claim for the identity token. Defaults to the provider resource name for the current run phase, which HCP Terraform derives from the values you provide for `RUN_PROVIDER_RESOURCE_NAME`, `PLAN_PROVIDER_RESOURCE_NAME`, and `APPLY_PROVIDER_RESOURCE_NAME`. | Requires **v1.15.1** or later if you use self-managing agents. This is one of the default `aud` formats that HCP accepts. | +| `TFC_HCP_PLAN_PROVIDER_RESOURCE_NAME`
`TFC_HCP_PLAN_PROVIDER_RESOURCE_NAME[_TAG]`
`TFC_DEFAULT_HCP_PLAN_PROVIDER_RESOURCE_NAME` | The resource name of the workload identity provider that will HCP Terraform will use to authenticate the agent during the plan phase of a run. | Requires **v1.15.1** or later if self-managing agents. Will fall back to the value of `RUN_PROVIDER_RESOURCE_NAME` if not provided. | +| `TFC_HCP_APPLY_PROVIDER_RESOURCE_NAME`
`TFC_HCP_APPLY_PROVIDER_RESOURCE_NAME[_TAG]`
`TFC_DEFAULT_HCP_APPLY_PROVIDER_RESOURCE_NAME` | The resource name of the workload identity provider that will HCP Terraform will use to authenticate the agent during the apply phase of a run. | Requires **v1.15.1** or later if self-managing agents. Will fall back to the value of `RUN_PROVIDER_RESOURCE_NAME` if not provided. | + +## Configure the HCP Provider + +Do not set the `HCP_CRED_FILE` environment variable when configuring the HCP provider, or `HCP_CRED_FILE` will conflict with the dynamic credentials authentication process. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.15.1](/terraform/cloud-docs/agents/changelog#1-15-1-05-01-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct HCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, refer to [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +Add the following variable to your Terraform configuration to set up additional dynamic credential configurations with the HCP provider. This variable lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_hcp_dynamic_credentials" { + description = "Object containing HCP dynamic credentials configuration" + type = object({ + default = object({ + credential_file = string + }) + aliases = map(object({ + credential_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "hcp" { + credential_file = var.tfc_hcp_dynamic_credentials.default.credential_file +} + +provider "hcp" { + alias = "ALIAS1" + credential_file = var.tfc_hcp_dynamic_credentials.aliases["ALIAS1"].credential_file +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration.mdx new file mode 100644 index 0000000000..984c8ce7a7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration.mdx @@ -0,0 +1,102 @@ +--- +page_title: >- + HCP Vault Secrets-Backed Dynamic Credentials with the AWS Provider - + Workspaces - Terraform Enterprise +description: >- + Use OpenID Connect and HCP Vault Secrets to get short-term credentials for the + AWS Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# HCP Vault Secrets-Backed Dynamic Credentials with the AWS Provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with HCP to use [HCP Vault Secrets-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed) with the AWS provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure HCP Provider Credentials](#configure-hcp-provider-credentials)**: Set up a trust configuration between HCP Vault Secrets and HCP Terraform, create HCP roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure HCP Vault Secrets](#configure-hcp-vault-secrets-aws-secrets-engine)**: Set up your HCP project's AWS integration and dynamic secret. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use HCP Vault Secrets-backed dynamic credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with HCP Vault Secrets-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with AWS via HCP Vault Secrets-generated credentials during the plan and apply phase of each run. The AWS provider's authentication is only valid for the length of the plan or apply phase. + +## Configure HCP Provider Credentials + +You must first set up HCP dynamic provider credentials before you can use HCP Vault Secrets-backed dynamic credentials. This includes creating a service principal, configuring trust between HCP and HCP Terraform, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for HCP dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration). + +## Configure HCP Vault Secrets AWS Secrets Engine + +Follow the instructions in the HCP Vault Secrets documentation for [setting up the AWS integration in your HCP project](/hcp/docs/vault-secrets/dynamic-secrets/aws). + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with AWS using HCP Vault Secrets-backed dynamic credentials. These variables are in addition to those you previously set while configuring [HCP provider credentials](#configure-hcp-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +### Required Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_AWS_AUTH`
`TFC_HVS_BACKED_AWS_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.16.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with AWS. | +| `TFC_HVS_BACKED_AWS_RUN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_AWS_HCP_CONFIG`
`TFC_HVS_BACKED_AWS_HCP_CONFIG[_TAG]`
`TFC_DEFAULT_HVS_BACKED_AWS_HCP_CONFIG` | The name of the non-default HCP configuration for workspaces using [multiple HCP configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.16.0** or later if self-managing agents. Will fall back to using the default HCP Vault Secrets configuration if not provided. | +| `TFC_HVS_BACKED_AWS_PLAN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the plan phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | +| `TFC_HVS_BACKED_AWS_APPLY_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the apply phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +## Configure Terraform Providers + +The final step is to directly configure your AWS and HCP Vault Secrets providers. + +### Configure the AWS Provider + +Ensure you pass a value for the `region` argument in your AWS provider configuration block or set the `AWS_REGION` variable in your workspace. + +Ensure you are not using any of the arguments or methods mentioned in the [authentication and configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration) section of the provider documentation. Otherwise, these settings may interfere with dynamic provider credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct HCP Vault Secrets-backed AWS setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_hvs_backed_aws_dynamic_credentials" { + description = "Object containing HCP Vault Secrets-backed AWS dynamic credentials configuration" + type = object({ + default = object({ + shared_credentials_file = string + }) + aliases = map(object({ + shared_credentials_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "aws" { + shared_credentials_files = [var.tfc_hvs_backed_aws_dynamic_credentials.default.shared_credentials_file] +} + +provider "aws" { + alias = "ALIAS1" + shared_credentials_files = [var.tfc_hvs_backed_aws_dynamic_credentials.aliases["ALIAS1"].shared_credentials_file] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration.mdx new file mode 100644 index 0000000000..725342406e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration.mdx @@ -0,0 +1,119 @@ +--- +page_title: >- + HCP Vault Secrets-Backed Dynamic Credentials with the GCP Provider - + Workspaces - Terraform Enterprise +description: >- + Use OpenID Connect and HCP Vault Secrets to get short-term credentials for the + GCP Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# HCP Vault Secrets-Backed Dynamic Credentials with the GCP Provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with HCP to use [HCP Vault Secrets-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed) with the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure HCP Provider Credentials](#configure-hcp-provider-credentials)**: Set up a trust configuration between HCP Vault Secrets and HCP Terraform, create HCP Vault Secrets roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure HCP Vault Secrets](#configure-hcp-vault-secrets-gcp-secrets-engine)**: Set up your HCP project's GCP integration and dynamic secret. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use HCP Vault Secrets-backed dynamic credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with HCP Vault Secrets-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with GCP via HCP Vault Secrets-generated credentials during the plan and apply phase of each run. The GCP provider's authentication is only valid for the length of the plan or apply phase. + +## Configure HCP Provider Credentials + +You must first set up HCP dynamic provider credentials before you can use HCP Vault Secrets-backed dynamic credentials. This includes creating a service principal, configuring trust between HCP and HCP Terraform, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for HCP dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration). + +## Configure HCP Vault Secrets GCP Secrets Engine + +Follow the instructions in the HCP Vault Secrets documentation for [setting up the GCP integration in your HCP project](/hcp/docs/vault-secrets/dynamic-secrets/gcp). + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with GCP using HCP Vault Secrets-backed dynamic credentials. These variables are in addition to those you previously set while configuring [HCP provider credentials](#configure-hcp-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +### Required Common Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_GCP_AUTH`
`TFC_HVS_BACKED_GCP_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.16.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with GCP. | +| `TFC_HVS_BACKED_GCP_RUN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +### Optional Common Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_GCP_HCP_CONFIG`
`TFC_HVS_BACKED_GCP_HCP_CONFIG[_TAG]`
`TFC_DEFAULT_HVS_BACKED_GCP_HCP_CONFIG` | The name of the non-default HCP configuration for workspaces using [multiple HCP configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.16.0** or later if self-managing agents. Will fall back to using the default HCP Vault Secrets configuration if not provided. | +| `TFC_HVS_BACKED_GCP_PLAN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the plan phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | +| `TFC_HVS_BACKED_GCP_APPLY_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the apply phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +## Configure Terraform Providers + +The final step is to directly configure your GCP and HCP Vault Secrets providers. + +### Configure the GCP Provider + +Ensure you pass values for the `project` and `region` arguments into the provider configuration block. + +Ensure you are not setting values or environment variables for `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`. Otherwise, these values may interfere with dynamic provider credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct HCP Vault Secrets-backed GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_hvs_backed_gcp_dynamic_credentials" { + description = "Object containing HCP Vault Secrets-backed GCP dynamic credentials configuration" + type = object({ + default = object({ + credentials = string + access_token = string + }) + aliases = map(object({ + credentials = string + access_token = string + })) + }) +} +``` + +#### Example Usage + +##### Access Token + +```hcl +provider "google" { + access_token = var.tfc_hvs_backed_gcp_dynamic_credentials.default.access_token +} + +provider "google" { + alias = "ALIAS1" + access_token = var.tfc_hvs_backed_gcp_dynamic_credentials.aliases["ALIAS1"].access_token +} +``` + +##### Credentials + +```hcl +provider "google" { + credentials = var.tfc_hvs_backed_gcp_dynamic_credentials.default.credentials +} + +provider "google" { + alias = "ALIAS1" + credentials = var.tfc_hvs_backed_gcp_dynamic_credentials.aliases["ALIAS1"].credentials +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/index.mdx new file mode 100644 index 0000000000..a60b0e4b12 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/index.mdx @@ -0,0 +1,38 @@ +--- +page_title: HCP Vault Secrets-backed dynamic credentials overview +description: >- + HCP Vault Secrets-backed dynamic credentials improve security by leveraging + HCP Vault Secrets to generate temporary credentials for Terraform runs. + Configure HCP Vault Secrets-backed dynamic credentials for supported + providers. +source: terraform-docs-common +--- + +# HCP Vault Secrets-Backed Dynamic Credentials + +This topic provides an overview of how to use HCP Vault Secrets to generate temporary credentials for providers so that you can securely use them in HCP Terraform runs. + +## Introduction + +Configuring [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) with different cloud providers is suitable for most use cases, but you can use HCP Vault Secrets-backed dynamic credentials to centralize and consolidate cloud credential management. + +HCP Vault Secrets-backed dynamic credentials leverage HCP Vault Secrets' [dynamic secrets capability](/hcp/docs/vault-secrets/dynamic-secrets), which allows you to generate short-lived credentials for various providers. This means you can authenticate a HCP instance using workload identity tokens and use dynamic secret capabilities on that instance to generate dynamic credentials for the various providers. + +Refer to the [HCP Vault Secrets announcement](https://www.hashicorp.com/blog/hcp-vault-secrets-is-now-generally-available) to learn about the benefits of using HCP Vault Secrets to manage provider credentials. + +## Workflow + +Using HCP Vault Secrets-backed dynamic credentials in a workspace requires the following steps for each cloud platform: + +1. If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or newer. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). +2. Set up dynamic provider credentials with the HCP provider: You must first [configure dynamic credentials with the HCP provider](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration). +3. Configure the dynamic secrets integration: You must configure the desired Vault secrets integration in your HCP project, such as AWS or GCP. +4. Configure your HCP Terraform workspace: You must add specific environment variables to your workspace to tell HCP Terraform how to authenticate to other cloud providers during runs. Each cloud platform has its own set of environment variables that are necessary to configure dynamic credentials. +5. Complete the instructions for setting up HCP Vault Secrets-backed dynamic for [Amazon Web Services](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration) or [Google Cloud Platform](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration). + +### Access to metadata endpoints + +In order to verify signed JWTs, HCP must have network access to the following static OIDC metadata endpoints within HCP Terraform: + +- `/.well-known/openid-configuration`: Standard OIDC metadata. +- `/.well-known/jwks`: HCP Terraform public keys that cloud platforms use to verify the authenticity of tokens that claim to come from HCP Terraform. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/index.mdx new file mode 100644 index 0000000000..11a3902ea2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/index.mdx @@ -0,0 +1,59 @@ +--- +page_title: Dynamic provider credentials in Terraform Enterprise +description: >- + Dynamic provider credentials generate temporary credentials for Terraform + Enterprise runs. Learn how dynamic credentials for Vault, AWS, Azure, + Kubernetes, and GCP can improve your security. +source: terraform-docs-common +--- + +# Dynamic provider credentials + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +Using static credentials in your workspaces to authenticate providers presents a security risk, even if you rotate your credentials regularly. Dynamic provider credentials improve your security posture by letting you provision new, temporary credentials for each run. + +You can configure dynamic credentials for each HCP Terraform workspace. This workflow eliminates the need to manually manage and rotate credentials across your organization. It also lets you use the cloud platform’s authentication and authorization tools to scope permissions based on metadata, such as a run’s phase, its workspace, or its organization. + +## How Dynamic Credentials Work + +You configure a trust relationship between your cloud platform and HCP Terraform. As part of that process, you can define rules that let HCP Terraform workspaces and runs access specific resources. Then, the following process occurs for each Terraform plan and apply: + +1. HCP Terraform generates a [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens). The token is compliant with OpenID Connect protocol (OIDC) standards and includes information about the organization, workspace, and run stage. +2. When a plan or apply begins, HCP Terraform sends the workload identity token to the cloud platform, along with any other information needed to authenticate. +3. The cloud platform uses HCP Terraform’s public signing key to verify the workload identity token. +4. If verification succeeds, the cloud platform returns a set of fresh temporary credentials for HCP Terraform to use. +5. HCP Terraform sets up these credentials within the run environment for the Terraform provider to use. +6. The Terraform plan or apply proceeds. +7. When the plan or apply completes, the run environment is torn down and the temporary credentials are discarded. + +## Configure Dynamic Credentials + +Using dynamic credentials in a workspace requires the following steps for each cloud platform: + +1. **Set up a Trust Relationship:** You must configure a relationship between HCP Terraform and the other cloud platform. The exact details of this process will be different depending on the cloud platform. +2. **Configure Cloud Platform Access:** You must configure roles and policies for the cloud platform to define the workspace’s access to infrastructure resources. +3. **Configure HCP Terraform Workspace**: You must add specific environment variables to your workspace to tell HCP Terraform how to authenticate to the other cloud platform during plans and applies. Each cloud platform has its own set of environment variables to configure dynamic credentials. + +The process for each step is different for each cloud platform. Refer to the cloud platform configuration instructions for full details. You can configure dynamic credentials for the following platforms: + +- [Vault](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration) +- [Amazon Web Services](/terraform/enterprise/workspaces/dynamic-provider-credentials/aws-configuration) +- [Google Cloud Platform](/terraform/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration) +- [Azure](/terraform/enterprise/workspaces/dynamic-provider-credentials/azure-configuration) +- [Kubernetes](/terraform/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration) + +You can also use Vault to generate credentials for AWS, GCP, or Azure by setting up [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed), which take advantage of Vault's [secrets engines](/vault/docs/secrets) to generate temporary credentials. + +## Terraform Enterprise Specific Requirements + +### External Access to Metadata Endpoints + +In order to verify signed JWTs, cloud platforms must have network access to the following static OIDC metadata endpoints within TFE: + +1. `/.well-known/openid-configuration` - standard OIDC metadata. +2. `/.well-known/jwks` - TFE’s public key(s) that cloud platforms use to verify the authenticity of tokens that claim to come from TFE. + +### External Vault Policy + +If you are using an external Vault instance, you must ensure that your Vault instance has the correct policies setup as detailed in the [External Vault Requirements for Terraform Enterprise](/terraform/enterprise/requirements/data-storage/vault) documentation. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration.mdx new file mode 100644 index 0000000000..6cd1fbda1f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration.mdx @@ -0,0 +1,171 @@ +--- +page_title: >- + Use dynamic credentials with the Kubernetes and Helm providers in Terraform + Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the Kubernetes and Helm + Terraform providers in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the Kubernetes and Helm providers + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.13.1](/terraform/cloud-docs/agents/changelog#1-13-1-10-25-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Kubernetes to use [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the Kubernetes and Helm providers in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Kubernetes](#configure-kubernetes):** Set up a trust configuration between Kubernetes and HCP Terraform. Next, create Kubernetes role bindings for your HCP Terraform identities. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use dynamic credentials. +3. **[Configure the Kubernetes or Helm provider](#configure-the-provider)**: Set the required attributes on the provider block. + +Once you complete the setup, HCP Terraform automatically authenticates to Kubernetes during each run. The Kubernetes and Helm providers' authentication is valid for the length of a plan or apply operation. + +## Configure Kubernetes + +You must enable and configure an OIDC identity provider in the Kubernetes API. This workflow changes based on the platform hosting your Kubernetes cluster. HCP Terraform only supports dynamic credentials with Kubernetes in AWS and GCP. + +### Configure an OIDC identity provider + +Refer to the AWS documentation for guidance on [setting up an EKS cluster for OIDC authentication](https://docs.aws.amazon.com/eks/latest/userguide/authenticate-oidc-identity-provider.html). You can also refer to our [example configuration](https://github.com/hashicorp-education/learn-terraform-dynamic-credentials/tree/main/eks/trust). + +Refer to the GCP documentation for guidance on [setting up a GKE cluster for OIDC authentication](https://cloud.google.com/kubernetes-engine/docs/how-to/oidc). You can also refer to our [example configuration](https://github.com/hashicorp-education/learn-terraform-dynamic-credentials/tree/main/gke/trust). + +When inputting an "issuer URL", use the address of HCP Terraform (`https://app.terraform.io` _without_ a trailing slash) or the URL of your Terraform Enterprise instance. The value of "client ID" is your audience in OIDC terminology, and it should match the value of the `TFC_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE` environment variable in your workspace. + +The OIDC identity resolves authentication to the Kubernetes API, but it first requires authorization to interact with that API. So, you must bind RBAC roles to the OIDC identity in Kubernetes. + +You can use both "User" and "Group" subjects in your role bindings. For OIDC identities coming from TFC, the "User" value is formatted like so: `organization::project::workspace::run_phase:`. + +You can extract the "Group" value from the token claim you configured in your cluster OIDC configuration. For details on the structure of the HCP Terraform token, refer to [Workload Identity](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens). + +Below, we show an example of a `RoleBinding` for the HCP Terraform OIDC identity. + +```hcl +resource "kubernetes_cluster_role_binding_v1" "oidc_role" { + metadata { + name = "odic-identity" + } + + role_ref { + api_group = "rbac.authorization.k8s.io" + kind = "ClusterRole" + name = var.rbac_group_cluster_role + } + + // Option A - Bind RBAC roles to groups + // + // Groups are extracted from the token claim designated by 'rbac_group_oidc_claim' + // + subject { + api_group = "rbac.authorization.k8s.io" + kind = "Group" + name = var.tfc_organization_name + } + + // Option B - Bind RBAC roles to user identities + // + // Users are extracted from the 'sub' token claim. + // Plan and apply phases get assigned different users identities. + // For HCP Terraform tokens, the format of the user id is always the one described bellow. + // + subject { + api_group = "rbac.authorization.k8s.io" + kind = "User" + name = "${var.tfc_hostname}#organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:plan" + } + + subject { + api_group = "rbac.authorization.k8s.io" + kind = "User" + name = "${var.tfc_hostname}#organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:apply" + } +} +``` + +If binding with "User" subjects, be aware that plan and apply phases are assigned different identities, each requiring specific bindings. Meaning you can tailor permissions for each Terraform operation. Planning operations usually require "read-only" permissions, while apply operations also require "write" access. + +!> **Warning**: Always check, at minimum, the audience and the organization's name to prevent unauthorized access from other HCP Terraform organizations. + +## Configure HCP Terraform + +You must set certain environment variables in your HCP Terraform workspace to configure HCP Terraform to authenticate with Kubernetes or Helm using dynamic credentials. You can set these as workspace variables, or if you’d like to share one Kubernetes role across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_KUBERNETES_PROVIDER_AUTH`
`TFC_KUBERNETES_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.14.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to Kubernetes. | +| `TFC_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE` | The audience name in your cluster's OIDC configuration, such as `kubernetes`. | Requires **v1.14.0** or later if self-managing agents. | + +## Configure the provider + +The Kubernetes and Helm providers share the same schema of configuration attributes for the provider block. The example below illustrates using the Kubernetes provider but the same configuration applies to the Helm provider. + +Make sure that you are not using any of the other arguments or methods listed in the [authentication](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication) section of the provider documentation as these settings may interfere with dynamic provider credentials. The only allowed provider attributes are `host` and `cluster_ca_certificate`. + +### Single provider instance + +HCP Terraform automatically sets the `KUBE_TOKEN` environment variable and includes the workload identity token. + +The provider needs to be configured with the URL of the API endpoint using the `host` attribute (or `KUBE_HOST` environment variable). In most cases, the `cluster_ca_certificate` (or `KUBE_CLUSTER_CA_CERT_DATA` environment variable) is also required. + +#### Example Usage + +```hcl +provider "kubernetes" { + host = var.cluster-endpoint-url + cluster_ca_certificate = base64decode(var.cluster-endpoint-ca) +} +``` + +### Multiple aliases + +You can add additional variables to handle multiple distinct Kubernetes clusters, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_kubernetes_dynamic_credentials" { + description = "Object containing Kubernetes dynamic credentials configuration" + type = object({ + default = object({ + token_path = string + }) + aliases = map(object({ + token_path = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "kubernetes" { + alias = "ALIAS1" + host = var.alias1-endpoint-url + cluster_ca_certificate = base64decode(var.alias1-cluster-ca) + token = file(var.tfc_kubernetes_dynamic_credentials.aliases["ALIAS1"].token_path) +} + +provider "kubernetes" { + alias = "ALIAS2" + host = var.alias1-endpoint-url + cluster_ca_certificate = base64decode(var.alias1-cluster-ca) + token = file(var.tfc_kubernetes_dynamic_credentials.aliases["ALIAS2"].token_path) +} +``` + +The `tfc_kubernetes_dynamic_credentials` variable is also available to use for single provider configurations, instead of the `KUBE_TOKEN` environment variable. + +```hcl +provider "kubernetes" { + host = var.cluster-endpoint-url + cluster_ca_certificate = base64decode(var.cluster-endpoint-ca) + token = file(var.tfc_kubernetes_dynamic_credentials.default.token_path) +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/manual-generation.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/manual-generation.mdx new file mode 100644 index 0000000000..ab6be885fb --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/manual-generation.mdx @@ -0,0 +1,42 @@ +--- +page_title: Manually generate workload identity tokens in Terraform Enterprise +description: >- + Learn how to generate workload identity tokens to allow Terraform runs to + safely authenticate with custom workflows and providers that do not natively + support dynamic credentials. +source: terraform-docs-common +--- + +# Manually generate workload identity tokens + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +If required for custom auth workflows or to perform auth with providers that are not natively supported by dynamic credentials, you can request that HCP Terraform inject a [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens) into the run environment for usage in agent hooks. + +## Configure HCP Terraform + +### Required Environment Variables + +You’ll need to set the following environment variable in your HCP Terraform workspace in order to have HCP Terraform inject a workload identity token into the run environment. You can set this as a workspace variable, or if you’d like to inject tokens with the same audience value across multiple workspaces, you can use a variable set. + +| Variable | Value | Notes | +| -------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TFC_WORKLOAD_IDENTITY_AUDIENCE` | The desired value for the token’s audience. | Requires **v1.7.0** or later if self-managing agents. Must be present and set or HCP Terraform will not inject a workload identity token into the run environment. | + +### Generating Multiple Tokens + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can generate multiple tokens if you want distinct audience values for different consumers of your workload identity tokens. For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +You can generate multiple tokens by specifying additional variables in the following format: `TFC_WORKLOAD_IDENTITY_AUDIENCE_[YOUR_TAG_HERE]`. + +Your tag can only contain letters, numbers, and underscores and can not use reserved keywords. The following keywords are reserved: `TYPE`. + +Each additional audience variable you specify generates an additional workload identity token that HCP Terraform stores in variables with the format: `TFC_WORKLOAD_IDENTITY_TOKEN_[YOUR_TAG_HERE]`. + +## Configure Agent Hooks + +After you've set the `TFC_WORKLOAD_IDENTITY_AUDIENCE` variable, each plan and apply will have a `TFC_WORKLOAD_IDENTITY_TOKEN` variable available in the run environment, which contains a [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens). + +You can use this environment variable in custom agent hooks to enable custom auth workflows or to perform auth with providers which are not natively supported by dynamic credentials. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations.mdx new file mode 100644 index 0000000000..24a076a110 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations.mdx @@ -0,0 +1,94 @@ +--- +page_title: Specify multiple dynamic credential configurations in Terraform Enterprise +description: >- + Specify multiple dynamic provider credential configurations for the same + workspace to create aliases for different provider configurations. +source: terraform-docs-common +--- + +# Specify multiple dynamic credential configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can create multiple dynamic credential configurations of the same provider in a workspace. + +Each configuration generates a distinct [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens), allowing you to create [aliases for different provider configurations](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can specify unique audience values per configuration, and [manually generate multiple tokens](/terraform/enterprise/workspaces/dynamic-provider-credentials/manual-generation). + +Specifying multiple dynamic credential configurations in HCP Terraform builds on the existing method of providing each provider's environment variables to a workspace. The process requires mapping well-known authentication [input variables](/terraform/language/values/variables) to the correct providers. + +## Configure HCP Terraform + +You can specify additional dynamic credentials configurations by defining and appending a “tag” to the end of your existing required environment variables: `[DYNAMIC_CREDENTIALS_VAR_NAME]_[YOUR_TAG]`. + +Your tag can only contain letters, numbers, and underscores and can not use reserved keywords. The following keywords are reserved: `TYPE`. + +### Example + +Using [Vault's dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration) setup as an example, we can create additional configurations by setting new tagged variables that match Vault's [required environment variables](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration#required-environment-variables). So, if you want to add a configuration with the tag `ALIAS1`, you must set environment variables for `TFC_VAULT_PROVIDER_AUTH_ALIAS1`, `TFC_VAULT_ADDR_ALIAS1`, and `TFC_VAULT_RUN_ROLE_ALIAS1`. + +### Default Values for Multiple Configurations + +Each environment variable has a corresponding default variable which you can use to share values across multiple configurations. In this way, you can set values common to multiple configurations a single time, rather than repeating them for each configuration. If you explicitly set the corresponding environment variable in addition to the default variable, the explicit value is given precedence. + +#### Example + +In the [example above](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations#example), if each of your Vault configurations used the same underlying Vault instance, you could define the Vault address a single time using the `TFC_DEFAULT_VAULT_ADDR` variable, and omit `TFC_VAULT_ADDR` and `TFC_VAULT_ADDR_ALIAS1`. If you add a third Vault configuration for a different Vault instance with the tag `ALIAS2`, you could set the variable `TFC_VAULT_ADDR_ALIAS2` to override the Vault address specifically for the `ALIAS2` configuration. + +## Configure Terraform Code + +Each supported provider has input variables you must declare in your Terraform code to use dynamic credentials with that provider. Each dynamic provider's documentation page lists the required variables for that provider. HCP Terraform provides values for these variables during runs, which you can use to authenticate HCP Terraform with providers using dynamic credentials. + +Use the input variable values that HCP Terraform provides to map configuration values to the correct provider blocks. Authentication information for the default provider exists in a variable's top-level `default` object, while each additional configuration exists under a variable's `aliases` map. HCP Terraform generates the keys of the `aliases` map based on the tag you define in your HCP Terraform configuration. + +~> **Important:** If you add additional configurations to a workspace, you need to manually map authentication information for all providers _including_ the default provider. + +### Example + +Continuing from the [example above](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations#example), after setting the required environment variables for your provider, [add the following code to your Terraform configuration](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration#required-terraform-variable). This lets HCP Terraform supply variable values that you can use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_dynamic_credentials" { + description = "Object containing Vault dynamic credentials configuration" + type = object({ + default = object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + }) + aliases = map(object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + })) + }) +} +``` + +Use the above object to map authentication information to the correct provider block. For this example, index into the `aliases` map with your alias's tag (`ALIAS1`) and the `default` provider object. + +```hcl +provider "vault" { + // Set this to true as HCP Terraform manages the token lifecycle + skip_child_token = true + address = var.tfc_vault_dynamic_credentials.default.address + namespace = var.tfc_vault_dynamic_credentials.default.namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.default.token_filename + } +} + +provider "vault" { + // Set this to true as HCP Terraform manages the token lifecycle + skip_child_token = true + alias = "ALIAS1" + address = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].address + namespace = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].token_filename + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration.mdx new file mode 100644 index 0000000000..31bcda6cda --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration.mdx @@ -0,0 +1,135 @@ +--- +page_title: >- + Use Vault-backed dynamic credentials with the AWS provider in Terraform + Enterprise +description: >- + Use OpenID Connect and Vault to get short-term credentials for the AWS + Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials with the AWS provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to use [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed) with the AWS provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault Dynamic Provider Credentials](#configure-vault-dynamic-provider-credentials)**: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure the Vault AWS Secrets Engine](#configure-vault-aws-secrets-engine)**: Set up the AWS secrets engine in your Vault instance. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with Vault-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with AWS via Vault-generated credentials during the plan and apply phase of each run. The AWS provider's authentication is only valid for the length of the plan or apply phase. + +## Configure Vault Dynamic Provider Credentials + +You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for Vault dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). + +# Configure Vault AWS Secrets Engine + +Follow the instructions in the Vault documentation for [setting up the AWS secrets engine in your Vault instance](/vault/docs/secrets/aws). You can also do this configuration through Terraform. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault-backed/aws). + +~> **Important**: carefully consider the limitations and differences between each supported credential type in the AWS secrets engine. These limitations carry over to HCP Terraform’s usage of these credentials for authenticating the AWS provider. + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with AWS using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring [Vault dynamic provider credentials](#configure-vault-dynamic-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Common Environment Variables + +The below variables apply to all AWS auth types. + +#### Required Common Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TFC_VAULT_BACKED_AWS_AUTH`
`TFC_VAULT_BACKED_AWS_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.8.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with AWS. | +| `TFC_VAULT_BACKED_AWS_AUTH_TYPE`
`TFC_VAULT_BACKED_AWS_AUTH_TYPE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_AUTH_TYPE` | Specifies the type of authentication to perform with AWS. Must be one of the following: `iam_user`, `assumed_role`, or `federation_token`. | Requires **v1.8.0** or later if self-managing agents. | +| `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_RUN_VAULT_ROLE` | The role to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE` and `TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE` are both provided. These variables are described [below](#optional-common-environment-variables). | + +#### Optional Common Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TFC_VAULT_BACKED_AWS_MOUNT_PATH`
`TFC_VAULT_BACKED_AWS_MOUNT_PATH[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_MOUNT_PATH` | The mount path of the AWS secrets engine in Vault. | Requires **v1.8.0** or later if self-managing agents. Defaults to `aws`. | +| `TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_PLAN_VAULT_ROLE` | The Vault role to use the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_APPLY_VAULT_ROLE` | The Vault role to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AWS_SLEEP_SECONDS`
`TFC_VAULT_BACKED_AWS_SLEEP_SECONDS[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_SLEEP_SECONDS` | The amount of time to wait, in seconds, after obtaining temporary credentials from Vault. e.g., `30` for 30 seconds. Must be 1500 seconds (25 minutes) or less. | Requires **v1.12.0** or later if self-managing agents. Can be used to mitigate eventual consistency issues in AWS when using the `iam_user` auth type. | +| `TFC_VAULT_BACKED_AWS_VAULT_CONFIG`
`TFC_VAULT_BACKED_AWS_VAULT_CONFIG[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_VAULT_CONFIG` | The name of the non-default Vault configuration for workspaces using [multiple Vault configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.12.0** or later if self-managing agents. Will fall back to using the default Vault configuration if not provided. | + +### Assumed Role Specific Environment Variables + +These environment variables are only valid if the `TFC_VAULT_BACKED_AWS_AUTH_TYPE` is `assumed_role`. + +#### Required Assumed Role Specific Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_RUN_ROLE_ARN` | The ARN of the role to assume in AWS. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN` and `TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN` are both provided. These variables are described [below](#optional-assume-role-specific-environment-variables). | + +#### Optional Assumed Role Specific Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_PLAN_ROLE_ARN` | The ARN of the role to use for the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN` if not provided. | +| `TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_APPLY_ROLE_ARN` | The ARN of the role to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN` if not provided. | + +## Configure Terraform Providers + +The final step is to directly configure your AWS and Vault providers. + +### Configure the AWS Provider + +Ensure you pass a value for the `region` argument in your AWS provider configuration block or set the `AWS_REGION` variable in your workspace. + +Ensure you are not using any of the arguments or methods mentioned in the [authentication and configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration) section of the provider documentation. Otherwise, these settings may interfere with dynamic provider credentials. + +### Configure the Vault Provider + +If you were previously using the Vault provider to authenticate the AWS provider, remove any existing usage of the AWS secrets engine from your Terraform Code. +This includes the [`vault_aws_access_credentials`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/aws_access_credentials) data source and any instances of [`vault_generic_secret`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret) you previously used to generate AWS credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Vault-backed AWS setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_backed_aws_dynamic_credentials" { + description = "Object containing Vault-backed AWS dynamic credentials configuration" + type = object({ + default = object({ + shared_credentials_file = string + }) + aliases = map(object({ + shared_credentials_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "aws" { + shared_credentials_files = [var.tfc_vault_backed_aws_dynamic_credentials.default.shared_credentials_file] +} + +provider "aws" { + alias = "ALIAS1" + shared_credentials_files = [var.tfc_vault_backed_aws_dynamic_credentials.aliases["ALIAS1"].shared_credentials_file] +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration.mdx new file mode 100644 index 0000000000..138e30f69b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration.mdx @@ -0,0 +1,152 @@ +--- +page_title: >- + Use Vault-backed dynamic credentials with the Azure provider in Terraform + Enterprise +description: >- + Use OpenID Connect and Vault to get short-term credentials for the Azure + Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials with the Azure provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to use [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed) with the Azure provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault Dynamic Provider Credentials](#configure-vault-dynamic-provider-credentials)**: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure the Vault Azure Secrets Engine](#configure-vault-azure-secrets-engine)**: Set up the Azure secrets engine in your Vault instance. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with Vault-backed Dynamic Credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with Azure via Vault-generated credentials during the plan and apply phase of each run. The Azure provider's authentication is only valid for the length of the plan or apply phase. + +## Configure Vault Dynamic Provider Credentials + +You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for Vault dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). + +# Configure Vault Azure Secrets Engine + +Follow the instructions in the Vault documentation for [setting up the Azure secrets engine in your Vault instance](/vault/docs/secrets/azure). You can also do this configuration through Terraform. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault-backed/azure). + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with Azure using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring [Vault dynamic provider credentials](#configure-vault-dynamic-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AZURE_AUTH`
`TFC_VAULT_BACKED_AZURE_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.8.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with Azure. | +| `TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE`
`TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_RUN_VAULT_ROLE` | The role to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE` and `TFC_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE` are both provided. These variables are described [below](#optional-environment-variables). | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AZURE_MOUNT_PATH`
`TFC_VAULT_BACKED_AZURE_MOUNT_PATH[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_MOUNT_PATH` | The mount path of the Azure secrets engine in Vault. | Requires **v1.8.0** or later if self-managing agents. Defaults to `azure`. | +| `TFC_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE`
`TFC_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE` | The Vault role to use the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE`
`TFC_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE` | The Vault role to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AZURE_SLEEP_SECONDS`
`TFC_VAULT_BACKED_AZURE_SLEEP_SECONDS[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_SLEEP_SECONDS` | The amount of time to wait, in seconds, after obtaining temporary credentials from Vault. e.g., `30` for 30 seconds. Must be 1500 seconds (25 minutes) or less. | Requires **v1.12.0** or later if self-managing agents. Can be used to mitigate eventual consistency issues in Azure. | +| `TFC_VAULT_BACKED_AZURE_VAULT_CONFIG`
`TFC_VAULT_BACKED_AZURE_VAULT_CONFIG[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_VAULT_CONFIG` | The name of the non-default Vault configuration for workspaces using [multiple Vault configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.12.0** or later if self-managing agents. Will fall back to using the default Vault configuration if not provided. | + +## Configure Terraform Providers + +The final step is to directly configure your Azure and Vault providers. + +### Configure the AzureRM or Microsoft Entra ID + +Ensure you pass a value for the `subscription_id` and `tenant_id` arguments in your provider configuration block or set the `ARM_SUBSCRIPTION_ID` and `ARM_TENANT_ID` variables in your workspace. + +Do not set values for `client_id`, `use_oidc`, or `oidc_token` in your provider configuration block. Additionally, do not set variable values for `ARM_CLIENT_ID`, `ARM_USE_OIDC`, or `ARM_OIDC_TOKEN`. + +### Configure the Vault Provider + +If you were previously using the Vault provider to authenticate the Azure provider, remove any existing usage of the Azure secrets engine from your Terraform Code. +This includes the [`vault_azure_access_credentials`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/azure_access_credentials) data source and any instances of [`vault_generic_secret`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret) you previously used to generate Azure credentials. + +### Specifying Multiple Configurations + +~> **Important:** Ensure you are using version **3.60.0** or later of the **AzureRM provider** and version **2.43.0** or later of the **Microsoft Entra ID provider** (previously Azure Active Directory) as required functionality was introduced in these provider versions. + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Vault-backed Azure setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_backed_azure_dynamic_credentials" { + description = "Object containing Vault-backed Azure dynamic credentials configuration" + type = object({ + default = object({ + client_id_file_path = string + client_secret_file_path = string + }) + aliases = map(object({ + client_id_file_path = string + client_secret_file_path = string + })) + }) +} +``` + +#### Example Usage + +##### AzureRM Provider + +```hcl +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + alias = "ALIAS1" + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` + +##### Microsoft Entra ID Provider (previously AzureAD) + +```hcl +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + alias = "ALIAS1" + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration.mdx new file mode 100644 index 0000000000..752c2887d9 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration.mdx @@ -0,0 +1,167 @@ +--- +page_title: >- + Use Vault-backed dynamic credentials with the GCP provider in Terraform + Enterprise +description: >- + Use OpenID Connect and Vault to get short-term credentials for the GCP + Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials with the GCP provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to use [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed) with the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault Dynamic Provider Credentials](#configure-vault-dynamic-provider-credentials)**: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure the Vault GCP Secrets Engine](#configure-vault-gcp-secrets-engine)**: Set up the GCP secrets engine in your Vault instance. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with Vault-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with GCP via Vault-generated credentials during the plan and apply phase of each run. The GCP provider's authentication is only valid for the length of the plan or apply phase. + +## Configure Vault Dynamic Provider Credentials + +You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for Vault dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). + +# Configure Vault GCP Secrets Engine + +Follow the instructions in the Vault documentation for [setting up the GCP secrets engine in your Vault instance](/vault/docs/secrets/gcp). You can also do this configuration through Terraform. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault-backed/gcp). + +~> **Important**: carefully consider the limitations and differences between each supported credential type in the GCP secrets engine. These limitations carry over to HCP Terraform’s usage of these credentials for authenticating the GCP provider. + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with GCP using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring [Vault dynamic provider credentials](#configure-vault-dynamic-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Common Environment Variables + +The below variables apply to all GCP auth types. + +#### Required Common Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_AUTH`
`TFC_VAULT_BACKED_GCP_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.8.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with GCP. | +| `TFC_VAULT_BACKED_GCP_AUTH_TYPE`
`TFC_VAULT_BACKED_GCP_AUTH_TYPE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_AUTH_TYPE` | Specifies the type of authentication to perform with GCP. Must be one of the following: `roleset/access_token`, `roleset/service_account_key`, `static_account/access_token`, or `static_account/service_account_key`. | Requires **v1.8.0** or later if self-managing agents. | + +#### Optional Common Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_MOUNT_PATH`
`TFC_VAULT_BACKED_GCP_MOUNT_PATH[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_MOUNT_PATH` | The mount path of the GCP secrets engine in Vault. | Requires **v1.8.0** or later if self-managing agents. Defaults to `gcp`. | +| `TFC_VAULT_BACKED_GCP_VAULT_CONFIG`
`TFC_VAULT_BACKED_GCP_VAULT_CONFIG[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_VAULT_CONFIG` | The name of the non-default Vault configuration for workspaces using [multiple Vault configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.12.0** or later if self-managing agents. Will fall back to using the default Vault configuration if not provided. | + +### Roleset Specific Environment Variables + +These environment variables are only valid if the `TFC_VAULT_BACKED_GCP_AUTH_TYPE` is `roleset/access_token` or `roleset/service_account_key`. + +#### Required Roleset Specific Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET`
`TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_RUN_VAULT_ROLESET` | The roleset to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET` and `TFC_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET` are both provided. These variables are described [below](#optional-roleset-specific-environment-variables). | + +#### Optional Roleset Specific Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET`
`TFC_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET` | The roleset to use for the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET` if not provided. | +| `TFC_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET`
`TFC_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET` | The roleset to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET` if not provided. | + +### Static Account Specific Environment Variables + +These environment variables are only valid if the `TFC_VAULT_BACKED_GCP_AUTH_TYPE` is `static_account/access_token` or `static_account/service_account_key`. + +#### Required Static Account Specific Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT`
`TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT` | The static account to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT` and `TFC_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT` are both provided. These variables are described [below](#optional-static-account-specific-environment-variables). | + +#### Optional Static Account Specific Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT`
`TFC_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT` | The static account to use for the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT` if not provided. | +| `TFC_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT`
`TFC_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT` | The static account to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT` if not provided. | + +## Configure Terraform Providers + +The final step is to directly configure your GCP and Vault providers. + +### Configure the GCP Provider + +Ensure you pass values for the `project` and `region` arguments into the provider configuration block. + +Ensure you are not setting values or environment variables for `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`. Otherwise, these values may interfere with dynamic provider credentials. + +### Configure the Vault Provider + +If you were previously using the Vault provider to authenticate the GCP provider, remove any existing usage of the GCP secrets engine from your Terraform Code. +This includes instances of [`vault_generic_secret`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret) that you previously used to generate GCP credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Vault-backed GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_backed_gcp_dynamic_credentials" { + description = "Object containing Vault-backed GCP dynamic credentials configuration" + type = object({ + default = object({ + credentials = string + access_token = string + }) + aliases = map(object({ + credentials = string + access_token = string + })) + }) +} +``` + +#### Example Usage + +##### Access Token + +```hcl +provider "google" { + access_token = var.tfc_vault_backed_gcp_dynamic_credentials.default.access_token +} + +provider "google" { + alias = "ALIAS1" + access_token = var.tfc_vault_backed_gcp_dynamic_credentials.aliases["ALIAS1"].access_token +} +``` + +##### Credentials + +```hcl +provider "google" { + credentials = var.tfc_vault_backed_gcp_dynamic_credentials.default.credentials +} + +provider "google" { + alias = "ALIAS1" + credentials = var.tfc_vault_backed_gcp_dynamic_credentials.aliases["ALIAS1"].credentials +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/index.mdx new file mode 100644 index 0000000000..29d2cd3396 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/index.mdx @@ -0,0 +1,52 @@ +--- +page_title: Use Vault-backed dynamic credentials in Terraform Enterprise +description: >- + Vault-backed dynamic credentials leverage Vault to generate temporary + credentials for Terraform Enterprise runs. Learn how Vault-backed dynamic + credentials for AWS, Azure, and GCP can improve your security. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +For most use cases, separately configuring [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) with different cloud providers works well. However, Vault-backed dynamic credentials are for those looking for a way to: + +1. Use Vault's secrets engines as a centralized way to manage and consolidate cloud credentials management. +2. Generate short-lived credentials without exposing their Terraform Enterprise instance's OIDC metadata endpoints to the broader public internet. + +The "Vault-backed" in "Vault-backed dynamic credentials" refers to Vault's [secrets engines](/vault/docs/secrets), which allow you to generate short-lived [dynamic secrets](https://www.vaultproject.io/use-cases/dynamic-secrets) for the AWS, GCP, or Azure providers. If you are using Terraform Enterprise and your Vault instance is configured within the same secure network, you can generate secrets while keeping your environment air-gapped. + +Vault-backed dynamic credentials combine the features of dynamic provider credentials and Vault's secrets engines. This means you can authenticate a Vault instance using workload identity tokens and use secrets engines on that instance to generate dynamic credentials for the AWS, GCP, and Azure providers. + +For a comparison of Vault-backed dynamic credentials and dynamic provider credentials, refer to the article [Why use Vault-backed dynamic credentials to secure HCP Terraform infrastructure?](https://www.hashicorp.com/blog/why-use-vault-backed-dynamic-credentials-to-secure-hcp-terraform-infrastructure) on the HashiCorp blog. + +## Configure Vault-Backed Dynamic Credentials + +Using Vault-backed dynamic credentials in a workspace requires the following steps for each cloud platform: + +1. **Set up Dynamic Provider Credentials with the Vault Provider:** You must first [configure dynamic credentials with the Vault provider](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). +2. **Configure the desired Secrets Engine**: You must configure the desired secrets engine in your Vault instance (i.e., AWS, GCP, or Azure). +3. **Configure HCP Terraform Workspace**: You must add specific environment variables to your workspace to tell HCP Terraform how to authenticate to other cloud providers during runs. Each cloud platform has its own set of environment variables that are necessary to configure dynamic credentials. + +Setting up Vault-backed dynamic credentials differs slightly for each cloud provider. You can configure Vault-backed dynamic credentials on the following platforms: + +- [Amazon Web Services](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration) +- [Google Cloud Platform](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration) +- [Azure](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration) + +## Terraform Enterprise Specific Requirements + +### Access to Metadata Endpoints + +In order to verify signed JWTs, Vault must have network access to the following static OIDC metadata endpoints within TFE: + +1. `/.well-known/openid-configuration` - standard OIDC metadata. +2. `/.well-known/jwks` - TFE’s public key(s) that cloud platforms use to verify the authenticity of tokens that claim to come from TFE. + +These endpoints **do not** need to be publicly exposed as long as your Vault instance can access them. + +### External Vault Policy + +If you are using an external Vault instance, you must ensure that your Vault instance has the correct policies setup as detailed in the [External Vault Requirements for Terraform Enterprise](/terraform/enterprise/requirements/data-storage/vault) documentation. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-configuration.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-configuration.mdx new file mode 100644 index 0000000000..8ed0483c1d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-configuration.mdx @@ -0,0 +1,225 @@ +--- +page_title: Use dynamic credentials with the Vault provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the Vault Terraform + provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the Vault provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the Vault provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault](#configure-vault):** Set up a trust configuration between Vault and HCP Terraform. Then, you must create Vault roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to Vault during each run. The Vault provider authentication is valid for the length of the plan or apply. Vault does not revoke authentication until the run is complete. + +If you are using Vault's [secrets engines](/vault/docs/secrets), you must complete the following set up before continuing to configure [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed). + +## Configure Vault + +You must enable and configure the JWT backend in Vault. These instructions use the Vault CLI commands, but you can also use Terraform to configure Vault. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault). + +### Enable the JWT Auth Backend + +Run the following command to enable the JWT auth backend in Vault: + +```shell +vault auth enable jwt +``` + +### Configure Trust with HCP Terraform + +You must configure Vault to trust HCP Terraform’s identity tokens and verify them using HCP Terraform’s public key. The following command configures the `jwt` auth backend in Vault to trust HCP Terraform as an OIDC identity provider: + +```shell +vault write auth/jwt/config \ + oidc_discovery_url="https://app.terraform.io" \ + bound_issuer="https://app.terraform.io" +``` + +The `oidc_discovery_url` and `bound_issuer` should both be the root address of HCP Terraform, including the scheme and without a trailing slash. + +#### Terraform Enterprise Specific Requirements + +If you are using a custom or self-signed CA certificate you may need to specify the CA certificate or chain of certificates, in PEM format, via the [`oidc_discovery_ca_pem`](/vault/api-docs/auth/jwt#oidc_discovery_ca_pem) argument as shown in the following example command: + +```shell +vault write auth/jwt/config \ + oidc_discovery_url="https://app.terraform.io" \ + bound_issuer="https://app.terraform.io" \ + oidc_discovery_ca_pem=@my-cert.pem +``` + +In the example above, `my-cert.pem` is a PEM formatted file containing the certificate. + +### Create a Vault Policy + +You must create a Vault policy that controls what paths and secrets your HCP Terraform workspace can access in Vault. +Create a file called tfc-policy.hcl with the following content: + +```hcl +# Allow tokens to query themselves +path "auth/token/lookup-self" { + capabilities = ["read"] +} + +# Allow tokens to renew themselves +path "auth/token/renew-self" { + capabilities = ["update"] +} + +# Allow tokens to revoke themselves +path "auth/token/revoke-self" { + capabilities = ["update"] +} + +# Configure the actual secrets the token should have access to +path "secret/*" { + capabilities = ["read"] +} +``` + +Then create the policy in Vault: + +```shell +vault policy write tfc-policy tfc-policy.hcl +``` + +### Create a JWT Auth Role + +Create a Vault role that HCP Terraform can use when authenticating to Vault. + +Vault offers a lot of flexibility in determining how to map roles and permissions in Vault to workspaces in HCP Terraform. You can have one role for each workspace, one role for a group of workspaces, or one role for all workspaces in an organization. You can also configure different roles for the plan and apply phases of a run. + +-> **Note:** If you set your `user_claim` to be per workspace, then Vault ties the entity it creates to that workspace's name. If you rename the workspace tied to your `user_claim`, Vault will create an additional identity object. To avoid this, update the alias name in Vault to your new workspace name before you update it in HCP Terraform. + +The following example creates a role called `tfc-role`. The role is mapped to a single workspace and HCP Terraform can use it for both plan and apply runs. + +Create a file called `vault-jwt-auth-role.json` with the following content: + +```json +{ + "policies": ["tfc-policy"], + "bound_audiences": ["vault.workload.identity"], + "bound_claims_type": "glob", + "bound_claims": { + "sub": +"organization:my-org-name:project:my-project-name:workspace:my-workspace-name:run_phase:*" + }, + "user_claim": "terraform_full_workspace", + "role_type": "jwt", + "token_ttl": "20m" +} +``` + +Then run the following command to create a role named `tfc-role` with this configuration in Vault: + +```shell +vault write auth/jwt/role/tfc-role @vault-jwt-auth-role.json +``` + +To understand all the available options for matching bound claims, refer to the [Terraform workload identity claim specification](/terraform/enterprise/workspaces/dynamic-provider-credentials) and the [Vault documentation on configuring bound claims](/vault/docs/auth/jwt#bound-claims). To understand all the options available when configuring Vault JWT auth roles, refer to the [Vault API documentation](/vault/api-docs/auth/jwt#create-role). + +!> **Warning:** you should always check, at minimum, the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations! + +#### Token TTLs + +We recommend setting token_ttl to a relatively short value. HCP Terraform can renew the token periodically until the plan or apply is complete, then revoke it to prevent it from being used further. + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with Vault using dynamic credentials. You can set these as workspace variables, or if you’d like to share one Vault role across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_PROVIDER_AUTH`
`TFC_VAULT_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to Vault. | +| `TFC_VAULT_ADDR`
`TFC_VAULT_ADDR[_TAG]`
`TFC_DEFAULT_VAULT_ADDR` | The address of the Vault instance to authenticate against. | Requires **v1.7.0** or later if self-managing agents. Will also be used to set `VAULT_ADDR` in the run environment. | +| `TFC_VAULT_RUN_ROLE`
`TFC_VAULT_RUN_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_RUN_ROLE` | The name of the Vault role to authenticate against (`tfc-role`, in our example). | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_VAULT_PLAN_ROLE` and `TFC_VAULT_APPLY_ROLE` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration#optional-environment-variables) | + +### Optional Environment Variables + +You may need to set these variables, depending on your Vault configuration and use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_NAMESPACE`
`TFC_VAULT_NAMESPACE[_TAG]`
`TFC_DEFAULT_VAULT_NAMESPACE` | The namespace to use when authenticating to Vault. | Requires **v1.7.0** or later if self-managing agents. Will also be used to set `VAULT_NAMESPACE` in the run environment. | +| `TFC_VAULT_AUTH_PATH`
`TFC_VAULT_AUTH_PATH[_TAG]`
`TFC_DEFAULT_VAULT_AUTH_PATH` | The path where the JWT auth backend is mounted in Vault. Defaults to jwt. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_VAULT_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_VAULT_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_VAULT_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to `vault.workload.identity`. | Requires **v1.7.0** or later if self-managing agents. Must match the `bound_audiences` configured for the role in Vault. | +| `TFC_VAULT_PLAN_ROLE`
`TFC_VAULT_PLAN_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_PLAN_ROLE` | The Vault role to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_RUN_ROLE` if not provided. | +| `TFC_VAULT_APPLY_ROLE`
`TFC_VAULT_APPLY_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_APPLY_ROLE` | The Vault role to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_RUN_ROLE` if not provided. | +| `TFC_VAULT_ENCODED_CACERT`
`TFC_VAULT_ENCODED_CACERT[_TAG]`
`TFC_DEFAULT_VAULT_ENCODED_CACERT` | A PEM-encoded CA certificate that has been Base64 encoded. | Requires **v1.9.0** or later if self-managing agents. This certificate will be used when connecting to Vault. May be required when connecting to Vault instances that use a custom or self-signed certificate. | + +## Vault Provider Configuration + +Once you set up dynamic credentials for a workspace, HCP Terraform automatically authenticates to Vault for each run. Do not pass the `address`, `token`, or `namespace` arguments into the provider configuration block. HCP Terraform sets these values as environment variables in the run environment. + +You can use the Vault provider to read static secrets from Vault and use them with other Terraform resources. You can also access the other resources and data sources available in the [Vault provider documentation](https://registry.terraform.io/providers/hashicorp/vault/latest). You must adjust your [Vault policy](#create-a-vault-policy) to give your HCP Terraform workspace access to all required Vault paths. + +~> **Important:** data sources that use secrets engines to generate dynamic secrets must not be used with Vault dynamic credentials. You can use Vault's dynamic secrets engines for AWS, GCP, and Azure by adding additional configurations. For more details, see [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed). + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +~> **Important:** Ensure you are using version **3.18.0** or later of the **Vault provider** as the required [`auth_login_token_file`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs#token-file) block was introduced in this provider version. + +You can add additional variables to handle multiple distinct Vault setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_dynamic_credentials" { + description = "Object containing Vault dynamic credentials configuration" + type = object({ + default = object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + }) + aliases = map(object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "vault" { + // skip_child_token must be explicitly set to true as HCP Terraform manages the token lifecycle + skip_child_token = true + address = var.tfc_vault_dynamic_credentials.default.address + namespace = var.tfc_vault_dynamic_credentials.default.namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.default.token_filename + } +} + +provider "vault" { + // skip_child_token must be explicitly set to true as HCP Terraform manages the token lifecycle + skip_child_token = true + alias = "ALIAS1" + address = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].address + namespace = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].token_filename + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens.mdx new file mode 100644 index 0000000000..26851ac640 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens.mdx @@ -0,0 +1,99 @@ +--- +page_title: Workload identity in Terraform Enterprise +description: >- + Learn how workload identity uses OpenID Connect (OIDC) to allow Terraform + plans and applies to safely authenticate to external systems. +source: terraform-docs-common +--- + +# Workload identity + +Dynamic Provider Credentials are powered by Terraform Workload Identity, which allows HCP Terraform to present information about a Terraform workload to an external system – like its workspace, organization, or whether it’s a plan or apply – and allows other external systems to verify that the information is accurate. + +You can think of it like an identity card for your Terraform runs: one that comes with a way for another system to easily verify whether the card is genuine. If the other system can confirm that the ID card is legitimate, it can trust the information the card contains and use it to decide whether to let that Terraform workload in the door. + +The “identity card” in this analogy is a workload identity token: a JSON Web Token (JWT) that contains information about a plan or apply, is signed by HCP Terraform’s private key, and expires at the end of the plan or apply timeout. Other systems can use HCP Terraform’s [public key](https://app.terraform.io/.well-known/jwks) to verify that a token that claims to be from HCP Terraform is genuine and has not been tampered with. + +This workflow is built on the [OpenID Connect protocol](https://openid.net/connect/), a trusted standard for verifying identity across different systems. + +## Token Specification + +Workload identity tokens contain useful metadata in their payloads, known as _claims_. This is the equivalent of the name and date of birth on an identity card. Once a cloud platform verifies a token using HCP Terraform’s public key, it can look at the claims in the identity token to either match it to the correct permissions or reject it. + +You don’t need to understand the full token specification and what every claim means in order to use dynamic credentials, but it’s useful for debugging. + +### Token Structure + +The following example shows a decoded HCP Terraform workload identity token: + +#### Header + +```json +{ + "typ": "JWT", + "alg": "RS256", + "kid": "j-fFp9evPJAzV5I2_58HY5UvdCK6Q4LLB1rnPOUfQAk" +} +``` + +#### Payload + +```json +{ + "jti": "1192426d-b525-4fde-9d42-f238be437bbd", + "iss": "https://app.terraform.io", + "aud": "my-example-audience", + "iat": 1650486122, + "nbf": 1650486117, + "exp": 1650486422, + "sub": "organization:my-org:project:Default Project:workspace:my-workspace:run_phase:apply", + "terraform_organization_id": "org-GRNbCjYNpBB6NEH9", + "terraform_organization_name": "my-org", + "terraform_project_id": "prj-vegSA59s1XPwMr2t", + "terraform_project_name": "Default Project", + "terraform_workspace_id": "ws-mbsd5E3Ktt5Rg2Xm", + "terraform_workspace_name": "my-workspace", + "terraform_full_workspace": "organization:my-org:project:Default Project:workspace:my-workspace", + "terraform_run_id": "run-X3n1AUXNGWbfECsJ", + "terraform_run_phase": "apply" +} +``` + +This payload includes a number of standard claims defined in the OIDC spec as well as a number of custom claims for further customization. + +### Standard Claims + +| Claim | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `jti` (JWT ID) | A unique identifier for each JWT. | +| `iss` (issuer) | Full URL of HCP Terraform or the Terraform Enterprise instance which signed the JWT. | +| `iat` (issued at) | Unix Timestamp when the JWT was issued. May be required by certain relying parties. | +| `nbf` (not before) | Unix Timestamp when the JWT can start being used. This will be the same as `iat` for tokens issued by HCP Terraform, but may be required by certain relying parties. | +| `aud` (audience) | Intended audience for the JWT. For example, `aws.workload.identity` for AWS. This can be customized. | +| `exp` (expiration) | Unix Timestamp based on the timeout of the run phase that it was issued for. This will follow the `plan` and `apply` timeouts set at the organization and site admin level. | +| `sub` (subject) | Fully qualified path to a workspace, followed by the run phase. For example: `organization:my-organization-name:project:Default Project:workspace:my-workspace-name:run_phase:apply` | + +### Custom Claims + +| Claim | Value | +| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `terraform_organization_id` (organization ID) | ID of the HCP Terraform organization performing the run. | +| `terraform_organization_name` (organization name) | Human-readable name of the HCP Terraform organization performing the run. Note that organization names can be changed. | +| `terraform_project_id` (project ID) | ID of the HCP Terraform project performing the run. | +| `terraform_project_name` (project name) | Human-readable name of the HCP Terraform project performing the run. Note that project names can be changed. The default project name is `Default Project`. | +| `terraform_workspace_id` (workspace ID) | ID of the HCP Terraform workspace performing the run. | +| `terraform_workspace_name` (workspace name) | Human-readable name of the HCP Terraform workspace performing the run. Note that workspace names can be changed. | +| `terraform_full_workspace` (fully qualified workspace) | Fully qualified path to a workspace. For example: `organization:my-organization-name:project:my-project-name:workspace:my-workspace-name` | +| `terraform_run_id` (run ID) | ID of the run that the token was generated for. This is intended to aid in traceability and logging. | +| `terraform_run_phase` (run phase) | The phase of the run this token was issued for. For example, `plan` or `apply` | + +### Configuring Trust with your Cloud Platform + +When configuring the trust relationship between HCP Terraform and your cloud platform, you’ll set up conditions to validate the contents of the identity token provided by HCP Terraform against your roles and policies. + +At the minimum, you should match against the following claims: + +- `aud` - the audience value of the token. This ensures that, for example, a workload identity token intended for AWS can’t be used to authenticate to Vault. +- `sub` - the subject value, which includes the organization and workspace performing the run. If you don’t match against at least the organization name, any organization or workspace on HCP Terraform will be able to access your cloud resources! + +You can match on as many claims as you want, depending on your cloud platform. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/health.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/health.mdx new file mode 100644 index 0000000000..21c209b819 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/health.mdx @@ -0,0 +1,245 @@ +--- +page_title: Health assessments in Terraform Enterprise +description: >- + Learn how Terraform Enterprise can continuously monitor workspaces to assess + whether their real infrastructure matches the requirements defined in your + Terraform configuration. +source: terraform-docs-common +--- + +# Health + +HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations: + +- [Drift detection](#drift-detection) determines whether your real-world infrastructure matches your Terraform configuration. +- [Continuous validation](#continuous-validation) determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. + +When you enable health assessments, HCP Terraform periodically runs health assessments for your workspace. Refer to [Health Assessment Scheduling](#health-assessment-scheduling) for details. + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +## Permissions + +Working with health assessments requires the following permissions: + +- To view health status for a workspace, you need read access to that workspace. +- To change organization health settings, you must be an [organization owner](/terraform/enterprise/users-teams-organizations/permissions#organization-owners). +- To change a workspace’s health settings, you must be an [administrator for that workspace](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins). + +- To trigger [on-demand health assessments](/terraform/enterprise/workspaces/health#on-demand-assessments) for a workspace, you must be an [administrator for that workspace](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins). + + +## Workspace requirements + +Workspaces require the following settings to receive health assessments: + +- Terraform version 0.15.4+ for drift detection only +- Terraform version 1.3.0+ for drift detection and continuous validation +- [Remote execution mode](/terraform/enterprise/workspaces/settings#execution-mode) or [Agent execution mode](/terraform/cloud-docs/agents/agent-pools#configure-workspaces-to-use-the-agent) for Terraform runs + +The latest Terraform run in the workspace must have been successful. If the most recent run ended in an errored, canceled, or discarded state, HCP Terraform pauses health assessments until there is a successfully applied run. + +The workspace must also have at least one run in which Terraform successfully applies a configuration. HCP Terraform does not perform health assessments in workspaces with no real-world infrastructure. + +## Enable health assessments + +You can enforce health assessments across all eligible workspaces in an organization within the [organization settings](/terraform/enterprise/users-teams-organizations/organizations#health). Enforcing health assessments at an organization-level overrides workspace-level settings. You can only enable health assessments within a specific workspace when HCP Terraform is not enforcing health assessments at the organization level. + +To enable health assessments within a workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to enable health assessments on. +2. Verify that your workspace satisfies the [requirements](#workspace-requirements). +3. Go to the workspace and click **Settings**, then click **Health**. +4. Select **Enable** under **Health Assessments**. +5. Click **Save settings**. + +## Health assessment scheduling + +When you enable health assessments for a workspace, HCP Terraform runs the first health assessment based on whether there are active Terraform runs for the workspace: + +- **No active runs:** A few minutes after you enable the feature. +- **Active speculative plan:** A few minutes after that plan is complete. +- **Other active runs:** During the next assessment period. + +After the first health assessment, HCP Terraform starts a new health assessment during the next assessment period if there are no active runs in the workspace. Health assessments may take longer to complete when you enable health assessments in many workspaces at once or your workspace contains a complex configuration with many resources. + +A health assessment never interrupts or interferes with runs. If you start a new run during a health assessment, HCP Terraform cancels the current assessment and runs the next assessment during the next assessment period. This behavior may prevent HCP Terraform from performing health assessments in workspaces with frequent runs. + +HCP Terraform pauses health assessments if the latest run ended in an errored state. This behavior occurs for all run types, including plan-only runs and speculative plans. Once the workspace completes a successful run, HCP Terraform restarts health assessments during the next assessment period. + +Terraform Enterprise administrators can modify their installation's [assessment frequency and number of maximum concurrent assessments](/terraform/enterprise/admin/application/general#health-assessments) from the admin settings console. + + + +### On-demand assessments + +-> **Note:** On-demand assessments are only available in the HCP Terraform user interface. + +If you are an administrator for a workspace and it satisfies all [assessment requirements](/terraform/enterprise/workspaces/health#workspace-requirements), you can trigger a new assessment by clicking **Start health assessment** on the workspace's **Health** page. + +After clicking **Start health assessment**, the workspace displays a message in the bottom lefthand corner of the page to indicate if it successfully triggered a new assessment. The time it takes to complete an assessment can vary based on network latency and the number of resources managed by the workspace. + +You cannot trigger another assessment while one is in progress. An on-demand assessment resets the scheduling for automated assessments, so HCP Terraform waits to run the next assessment until the next scheduled period. + + + +### Concurrency + +If you enable health assessments on multiple workspaces, assessments may run concurrently. Health assessments do not affect your concurrency limit. HCP Terraform also monitors and controls health assessment concurrency to avoid issues for large-scale deployments with thousands of workspaces. However, HCP Terraform performs health assessments in batches, so health assessments may take longer to complete when you enable them in a large number of workspaces. + +### Notifications + +HCP Terraform sends [notifications](/terraform/enterprise/workspaces/settings/notifications) about health assessment results according to your workspace’s settings. + +## Workspace health status + +On the organization's **Workspaces** page, HCP Terraform displays a **Health warning** status for workspaces with infrastructure drift or failed continuous validation checks. + +On the right of a workspace’s overview page, HCP Terraform displays a **Health** bar that summarizes the results of the last health assessment. + +- The **Drift** summary shows the total number of resources in the configuration and the number of resources that have drifted. +- The **Checks** summary shows the number of passed, failed, and unknown statuses for objects with continuous validation checks. + + + +### View workspace health in explorer + +The [Explorer page](/terraform/enterprise/workspaces/explorer) presents a condensed overview of the health status of the workspaces within your organization. You can see the following information: + +- Workspaces that are monitoring workspace health +- Status of any configured continuous validation checks +- Count of drifted resources for each workspace + +For additional details on the data available for reporting, refer to the [Explorer](/terraform/enterprise/workspaces/explorer) documentation. + +![Viewing Workspace Health in Explorer](/img/docs/tfc-explorer-health.png) + + + +## Drift detection + +Drift detection helps you identify situations where your actual infrastructure no longer matches the configuration defined in Terraform. This deviation is known as _configuration drift_. Configuration drift occurs when changes are made outside Terraform's regular process, leading to inconsistencies between the remote objects and your configured infrastructure. + +For example, a teammate could create configuration drift by directly updating a storage bucket's settings with conflicting configuration settings using the cloud provider's console. Drift detection could detect these differences and recommend steps to address and rectify the discrepancies. + +Configuration drift differs from state drift. Drift detection does not detect state drift. + +Configuration drift happens when external changes affecting remote objects invalidate your infrastructure configuration. State drift occurs when external changes affecting remote objects _do not_ invalidate your infrastructure configuration. Refer to [Refresh-Only Mode](/terraform/enterprise/run/modes-and-options#refresh-only-mode) to learn more about remediating state drift. + +### View workspace drift + +To view the drift detection results from the latest health assessment, go to the workspace and click **Health > Drift**. If there is configuration drift, HCP Terraform proposes the necessary changes to bring the infrastructure back in sync with its configuration. + +### Resolve drift + +You can use one of the following approaches to correct configuration drift: + +- **Overwrite drift**: If you do not want the drift's changes, queue a new plan and apply the changes to revert your real-world infrastructure to match your Terraform configuration. +- **Update Terraform configuration:** If you want the drift's changes, modify your Terraform configuration to include the changes and push a new configuration version. This prevents Terraform from reverting the drift during the next apply. Refer to the [Manage Resource Drift](/terraform/tutorials/state/resource-drift) tutorial for a detailed example. + +## Continuous validation + +Continuous validation regularly verifies whether your configuration’s custom assertions continue to pass, validating your infrastructure. For example, you can monitor whether your website returns an expected status code, or whether an API gateway certificate is valid. Identifying failed assertions helps you resolve the failure and prevent errors during your next time Terraform operation. + +Continuous validation evaluates preconditions, postconditions, and check blocks as part of an assessment, but we recommend using [check blocks](/terraform/language/checks) for post-apply monitoring. Use check blocks to create custom rules to validate your infrastructure's resources, data sources, and outputs. + +### Preventing false positives + +Health assessments create a speculative plan to access the current state of your infrastructure. Terraform evaluates any check blocks in your configuration as the last step of creating the speculative plan. If your configuration relies on data sources and the values queried by a data source change between the time of your last run and the assessment, the speculative plan will include those changes. HCP Terraform will not modify your infrastructure as part of an assessment, but it can use those updated values to evaluate checks. This may lead to false positive results for alerts since your infrastructure did not yet change. + +To ensure your checks evaluate the current state of your configuration instead of against a possible future change, use nested data sources that query your actual resource configuration, rather than a computed latest value. Refer to the [AMI image scenario](#asserting-up-to-date-amis-for-compute-instances) below for an example. + +### Example use cases + +Review the provider documentation for `check` block examples with [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/continuous-validation-examples), [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/tfc-check-blocks), and [GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/google-continuous-validation). + +#### Monitoring the health of a provisioned website + +The following example uses the [HTTP](https://registry.terraform.io/providers/hashicorp/http/latest/docs) Terraform provider and a [scoped data source](/terraform/language/checks#scoped-data-sources) within a [`check` block](/terraform/language/checks) to assert the Terraform website returns a `200` status code, indicating it is healthy. + +```hcl +check "health_check" { + data "http" "terraform_io" { + url = "https://www.terraform.io" + } + + assert { + condition = data.http.terraform_io.status_code == 200 + error_message = "${data.http.terraform_io.url} returned an unhealthy status code" + } +} +``` + +Continuous Validation alerts you if the website returns any status code besides `200` while Terraform evaluates this assertion. You can also find failures in your workspace's [Continuous Validation Results](#view-continuous-validation-results) page. You can configure continuous validation alerts in your workspace's [notification settings](/terraform/enterprise/workspaces/settings/notifications). + +#### Monitoring certificate expiration + +[Vault](https://www.vaultproject.io/) lets you secure, store, and tightly control access to tokens, passwords, certificates, encryption keys, and other sensitive data. The following example uses a `check` block to monitor for the expiration of a Vault certificate. + +```hcl +resource "vault_pki_secret_backend_cert" "app" { + backend = vault_mount.intermediate.path + name = vault_pki_secret_backend_role.test.name + common_name = "app.my.domain" +} + +check "certificate_valid" { + assert { + condition = !vault_pki_secret_backend_cert.app.renew_pending + error_message = "Vault cert is ready to renew." + } +} +``` + +#### Asserting up-to-date AMIs for compute instances + +[HCP Packer](/hcp/docs/packer) stores metadata about your [Packer](https://www.packer.io/) images. The following example check fails when there is a newer AMI version available. + +```hcl +data "hcp_packer_artifact" "hashiapp_image" { + bucket_name = "hashiapp" + channel_name = "latest" + platform = "aws" + region = "us-west-2" +} + +resource "aws_instance" "hashiapp" { + ami = data.hcp_packer_artifact.hashiapp_image.external_identifier + instance_type = var.instance_type + associate_public_ip_address = true + subnet_id = aws_subnet.hashiapp.id + vpc_security_group_ids = [aws_security_group.hashiapp.id] + key_name = aws_key_pair.generated_key.key_name + + tags = { + Name = "hashiapp" + } +} + +check "ami_version_check" { + data "aws_instance" "hashiapp_current" { + instance_tags = { + Name = "hashiapp" + } + } + + assert { + condition = aws_instance.hashiapp.ami == data.hcp_packer_artifact.hashiapp_image.external_identifier + error_message = "Must use the latest available AMI, ${data.hcp_packer_artifact.hashiapp_image.external_identifier}." + } +} +``` + +### View continuous validation results + +To view the continuous validation results from the latest health assessment, go to the workspace and click **Health > Continuous validation**. + +The page shows all of the resources, outputs, and data sources with custom assertions that HCP Terraform evaluated. Next to each object, HCP Terraform reports whether the assertion passed or failed. If one or more assertions fail, HCP Terraform displays the error messages for each assertion. + +The health assessment page displays each assertion by its [named value](/terraform/language/expressions/references). A `check` block's named value combines the prefix `check` with its configuration name. + +If your configuration contains multiple [preconditions and postconditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) within a single resource, output, or data source, HCP Terraform will not show the results of individual conditions unless they fail. If all custom conditions on the object pass, HCP Terraform reports that the entire check passed. The assessment results will display the results of any precondition and postconditions alongside the results of any assertions from `check` blocks, identified by the named values of their parent block. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/index.mdx new file mode 100644 index 0000000000..61267c1f5b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/index.mdx @@ -0,0 +1,100 @@ +--- +page_title: Terraform Enterprise workspaces +description: >- + A workspace is a group of infrastructure resources managed by Terraform + Enterprise. Learn what workspaces contain, how they perform Terraform runs, + and how to create and organize them. +source: terraform-docs-common +--- + +# Workspaces + +This topic provides an overview of the workspaces resource in HCP Terraform and Terraform Enterprise. A workspace is a group of infrastructure resources managed by Terraform. + +## Introduction + +Working with Terraform involves managing collections of infrastructure resources, and most organizations manage many different collections. + +When run locally, Terraform manages each collection of infrastructure with a persistent working directory, which contains a configuration, state data, and variables. Since Terraform CLI uses content from the directory it runs in, you can organize infrastructure resources into meaningful groups by keeping their configurations in separate directories. + +HCP Terraform manages infrastructure collections with workspaces instead of directories. A workspace contains everything Terraform needs to manage a given collection of infrastructure, and separate workspaces function like completely separate working directories. + +> **Hands-on:** Try the [Create a Workspace](/terraform/tutorials/cloud-get-started/cloud-workspace-create) tutorial. + +## Workspace Contents + +HCP Terraform workspaces and local working directories serve the same purpose, but they store their data differently: + +| Component | Local Terraform | HCP Terraform | +| ----------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | +| Terraform configuration | On disk | In linked version control repository, or periodically uploaded via API/CLI | +| Variable values | As `.tfvars` files, as CLI arguments, or in shell environment | In workspace | +| State | On disk or in remote backend | In workspace | +| Credentials and secrets | In shell environment or entered at prompts | In workspace, stored as sensitive variables | + +In addition to the basic Terraform content, HCP Terraform keeps some additional data for each workspace: + +- **State versions:** Each workspace retains backups of its previous state files. Although only the current state is necessary for managing resources, the state history can be useful for tracking changes over time or recovering from problems. Refer to [Terraform State in HCP Terraform](/terraform/enterprise/workspaces/state) for more details. + +- **Run history:** When HCP Terraform manages a workspace's Terraform runs, it retains a record of all run activity, including summaries, logs, a reference to the changes that caused the run, and user comments. Refer to [Viewing and Managing Runs](/terraform/enterprise/run/manage) for more details. + + + +The top of each workspace shows a resource count, which reflects the number of resources recorded in the workspace’s state file. This includes both managed [resources](/terraform/language/resources/syntax) and [data sources](/terraform/language/data-sources). + + + +## Terraform Runs + +For workspaces with remote operations enabled (the default), HCP Terraform performs Terraform runs on its own disposable virtual machines, using that workspace's configuration, variables, and state. + +Refer to [Terraform Runs and Remote Operations](/terraform/enterprise/run/remote-operations) for more details. + +## HCP Terraform vs. Terraform CLI Workspaces + +Both HCP Terraform and Terraform CLI have features called workspaces, but they function differently. + +- HCP Terraform workspaces are required. They represent all of the collections of infrastructure in an organization. They are also a major component of role-based access in HCP Terraform. You can grant individual users and user groups permissions for one or more workspaces that dictate whether they can manage variables, perform runs, etc. You cannot manage resources in HCP Terraform without creating at least one workspace. + +- Terraform CLI workspaces are associated with a specific working directory and isolate multiple state files in the same working directory, letting you manage multiple groups of resources with a single configuration. The Terraform CLI does not require you to create CLI workspaces. Refer to [Workspaces](/terraform/language/state/workspaces) in the Terraform Language documentation for more details. + +## Planning and Organizing Workspaces + +We recommend that organizations break down large monolithic Terraform configurations into smaller ones, then assign each one to its own workspace and delegate permissions and responsibilities for them. HCP Terraform can manage monolithic configurations just fine, but managing infrastructure as smaller components is the best way to take full advantage of HCP Terraform's governance and delegation features. + +For example, the code that manages your production environment's infrastructure could be split into a networking configuration, the main application's configuration, and a monitoring configuration. After splitting the code, you would create "networking-prod", "app1-prod", "monitoring-prod" workspaces, and assign separate teams to manage them. + +Much like splitting monolithic applications into smaller microservices, this enables teams to make changes in parallel. In addition, it makes it easier to re-use configurations to manage other environments of infrastructure ("app1-dev," etc.). + +In Terraform Enterprise, administrators can use [Admin Settings](/terraform/enterprise/api-docs/admin/settings) to set the maximum number of workspaces for any single organization. You can also set a workspaces limit with the [tfe-terraform-provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/organization#workspace_limit). + +## Organize Workspaces with Projects + +Projects let you organize your workspaces into groups. + + + +-> **Note:** On HCP Terraform **Standard** Edition, you can assign project permissions to scope access to collections of workspaces based on business units and responsibilities. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. + + + +Refer to [Organize Workspaces with Projects](/terraform/enterprise/projects/manage) for more details. + +## Creating Workspaces + +You can create workspaces through the [HCP Terraform UI](/terraform/enterprise/workspaces/create), the [Workspaces API](/terraform/enterprise/api-docs/workspaces), or the [HCP Terraform CLI integration](/terraform/cli/cloud). + +## Workspace Health + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations: + +- Drift detection determines whether your real-world infrastructure matches your Terraform configuration. +- Continuous validation determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. + +You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings. Refer to [Health](/terraform/enterprise/workspaces/health) in the workspaces documentation for more details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/json-filtering.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/json-filtering.mdx new file mode 100644 index 0000000000..c70eb74e3f --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/json-filtering.mdx @@ -0,0 +1,117 @@ +--- +page_title: JSON data filtering in Terraform Enterprise +description: >- + Learn how to filter and create custom datasets on pages that display JSON data + in Terraform Enterprise. +source: terraform-docs-common +--- + +# JSON data filtering + +Certain pages where JSON data is displayed, such as the [state +viewer](/terraform/enterprise/workspaces/state) and [policy check JSON data +viewer](/terraform/enterprise/policy-enforcement/sentinel/json), allow you to filter the results. This +enables you to see just the data you need, and even create entirely new datasets +to see data in the way you want to see it! + +![entering a json filter](/img/docs/json-viewer-intro.png) + +-> **NOTE:** _Filtering_ the data in the JSON viewer is separate from +_searching_ it. To search, press Control-F (or Command-F on MacOS). You can +search and apply a filter at the same time. + +## Entering a Filter + +Filters are entered by putting the filter in the aptly named **filter** box in +the JSON viewer. After entering the filter, pressing **Apply** or the enter key +on your keyboard will apply the filter. The filtered results, if any, are +displayed in result box. Clearing the filter will restore the original JSON +data. + +![entering a json filter](/img/docs/sentinel-json-enter-filter.png) + +## Filter Language + +The JSON filter language is a small subset of the +[jq](https://stedolan.github.io/jq/) JSON filtering language. Selectors, +literals, indexes, slices, iterators, and pipes are supported, as are also array +and object construction. At this time, parentheses, and more complex operations +such as mathematical operators, conditionals, and functions are not supported. + +Below is a quick reference of some of the more basic functions to get you +started. + +### Selectors + +Selectors allow you to pick an index out of a JSON object, and are written as +`.KEY.SUBKEY`. So, as an example, given an object of +`{"foo": {"bar": "baz"}}`, and the filter `.foo.bar`, the result would be +displayed as `"baz"`. + +A single dot (`.`) without anything else always denotes the current value, +unaltered. + +### Indexes + +Indexes can be used to fetch array elements, or select non-alphanumeric object +fields. They are written as `[0]` or `["foo-bar"]`, depending on the purpose. + +Given an object of `{"foo-bar": ["baz", "qux"]}` and the filter of +`.["foo-bar"][0]`, the result would be displayed as `"baz"`. + +### Slices + +Arrays can be sliced to get a subset an array. The syntax is `[LOW:HIGH]`. + +Given an array of `[0, 1, 2, 3, 4]` and the filter of +`.[1:3]`, the result would be displayed as `[1, 2]`. This also illustrates that +the result of the slice operation is always of length HIGH-LOW. + +Slices can also be applied to strings, in which a substring is returned with the +same rules applied, with the first character of the string being index 0. + +### Iterators + +Iterators can iterate over arrays and objects. The syntax is `[]`. + +Iterators iterate over the _values_ of an object only. So given a object of +`{"foo": 1, "bar": 2}`, the filter `.[]` would yield an iteration of `1, 2`. + +Note that iteration results are not necessarily always arrays. Iterators are +handled in a special fashion when dealing with pipes and object creators (see +below). + +### Array Construction + +Wrapping an expression in brackets (`[ ... ]`) creates an array with the +sub-expressions inside the array. The results are always concatenated. + +For example, for an object of `{"foo": [1, 2], "bar": [3, 4]}`, the construction +expressions `[.foo[], .bar[]]` and `[.[][]]`, are the same, producing the +resulting array `[1, 2, 3, 4]`. + +### Object Construction + +Wrapping an expression in curly braces `{KEY: EXPRESSION, ...}` creates an +object. + +Iterators work uniquely with object construction in that an object is +constructed for each _iteration_ that the iterator produces. + +As a basic example, Consider an array `[1, 2, 3]`. While the expression +`{foo: .}` will produce `{"foo": [1, 2, 3]}`, adding an iterator to the +expression so that it reads `{foo: .[]}` will produce 3 individual objects: +`{"foo": 1}`, `{"foo": 2}`, and `{"foo": 3}`. + +### Pipes + +Pipes allow the results of one expression to be fed into another. This can be +used to re-write expressions to help reduce complexity. + +Iterators work with pipes in a fashion similar to object construction, where the +expression on the right-hand side of the pipe is evaluated once for every +iteration. + +As an example, for the object `{"foo": {"a": 1}, "bar": {"a": 2}}`, both the +expression `{z: .[].a}` and `.[] | {z: .a}` produce the same result: `{"z": 1}` +and `{"z": 2}`. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/access.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/access.mdx new file mode 100644 index 0000000000..8fd6acdce7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/access.mdx @@ -0,0 +1,54 @@ +--- +page_title: Manage access to workspaces in Terraform Enterprise +description: >- + Learn how to manage access to workspaces by adding teams and configuring their + permissions. +source: terraform-docs-common +--- + +# Manage access to workspaces + + + +-> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). + + + +HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. + +Teams with [admin access](/terraform/enterprise/users-teams-organizations/permissions) on a workspace can manage permissions for other teams on that workspace. Since newly created workspaces don't have any team permissions configured, the initial setup of a workspace's permissions requires the owners team or a team with permission to manage workspaces. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **API:** See the [Team Access APIs](/terraform/enterprise/api-docs/team-access).
+**Terraform:** See the `tfe` provider's [`tfe_team_access`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/team_access) resource. + +## Background + +HCP Terraform manages users' permissions to workspaces with teams. + +- [Workspace-level permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) can be granted to an individual team on a particular workspace. These permissions can be managed on the workspace by anyone with admin access to the workspace. +- In addition, some [organization-level permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) can be granted to a team which apply to every workspace in the organization. For example, the + [manage all workspaces](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces) and [manage all projects](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects) permissions grant the workspace-level admin permission to every workspace in the organization. Organization-level permissions can only be managed by organization owners. + +## Managing Workspace Access Permissions + +When a user creates a workspace, the following teams can access that workspace with full admin permissions: + +- [the owners team](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) +- teams with "Manage all workspaces" and/or “Manage all projects” [organization permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) +- teams with “Project Admin” project permissions + +You cannot override these teams' permissions through the workspace's specific permissions. + +To manage a team's access to a workspace, select "Team Access" from the workspace's "Settings" menu. + +This screen displays all teams granted workspace-level permissions to the workspace. To add a team, select "Add team and permissions". + +HCP Terraform displays the teams you can grant workspace access to. Select a team to continue and configure that team's permissions. + +There are four [fixed permissions sets](/terraform/enterprise/users-teams-organizations/permissions#fixed-permission-sets) available for basic usage: Read, Plan, Write, and Admin. + +To enable finer-grained selection of non-admin permissions, select "Customize permissions for this team". On this screen, you can select specific permissions to grant the team for the workspace. + +For more information on permissions, see [the documentation on Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/deletion.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/deletion.mdx new file mode 100644 index 0000000000..4daa48e161 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/deletion.mdx @@ -0,0 +1,125 @@ +--- +page_title: Destroy infrastructure resources and delete workspaces in Terraform Enterprise +description: >- + Learn how to clean up resources by destroying a workspace's infrastructure and + deleting a workspace in Terraform Enterprise. +source: terraform-docs-common +--- + +# Destroy infrastructure resources and delete workspaces + +HCP Terraform workspaces have two primary delete actions: + +- [Destroying infrastructure](#destroy-infrastructure) deletes resources managed by the HCP Terraform workspace by triggering a destroy run. +- [Deleting a workspace](#delete-workspaces) deletes the workspace itself without triggering a destroy run. + +In general, you should perform both actions in the above order when destroying a workspace to ensure resource cleanup for all of a workspace's managed infrastructure. + +## Destroy Infrastructure + +Destroy plans delete the infrastructure managed by a workspace. We recommend destroying the infrastructure managed by a workspace _before_ deleting the workspace itself. Otherwise, the unmanaged infrastructure resources will continue to exist but will become unmanaged, and you must go into your infrastructure providers to delete the resources manually. + +Before queuing a destroy plan, enable the **Allow destroy plans** toggle setting on this page. + +### Automatically Destroy + + + +@include 'tfc-package-callouts/ephemeral-workspaces.mdx' + + + +Configuring automatic infrastructure destruction for a workspace requires [admin permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) for that workspace. + +There are two main ways to automatically destroy a workspace's resources: + +- Schedule a run to destroy all resources in a workspace at a specific date and time. +- Configure HCP Terraform to destroy a workspace's infrastructure after a period of workspace inactivity. + +Workspaces can inherit auto-destroy settings from their project. Refer to [managing projects](/terraform/enterprise/projects/manage#automatically-destroy-inactive-workspaces) for more information. You can configure an individual workspace's auto-destroy settings to override the project's configuration. + +You can reduce your spending on infrastructure by automatically destroying temporary resources like development environments. + +After HCP Terraform performs an auto-destroy run, it unsets the `auto-destroy-at` field on the workspace. If you continue using the workspace, you can schedule another future auto-destroy run to remove any new resources. + +!> **Note:** Automatic destroy plans _do not_ prompt you for apply approval in the HCP Terraform user interface. We recommend only using this setting for development environments. + +You can schedule an auto-destroy run using the HCP Terraform web user interface, or the [workspace API](/terraform/enterprise/api-docs/workspaces). + +You can also schedule [notifications](/terraform/enterprise/workspaces/settings/notifications) to alert you 12 and 24 hours before an auto-destroy run, and to report auto-destroy run results. + +#### Destroy at a specific day and time + +To schedule an auto-destroy run at a specific time in HCP Terraform: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to destroy. +2. Choose **Settings** from the sidebar, then **Destruction and Deletion**. +3. Under **Automatically destroy**, click **Set up auto-destroy**. +4. Enter the desired date and time. HCP Terraform defaults to your local time zone for scheduling and displays how long until the scheduled operation. +5. Click **Confirm auto-destroy**. + +To cancel a scheduled auto-destroy run in HCP Terraform: + +1. Navigate to the workspace's **Settings** > **Destruction and Deletion** page. +2. Under **Automatically destroy**, click **Edit** next to your scheduled run's details. +3. Click **Remove**. + +#### Destroy if a workspace is inactive + +You can configure HCP Terraform to automatically destroy a workspace's infrastructure after a period of inactivity. +A workspace is _inactive_ if the workspace's state has not changed within your designated time period. + +!> **Caution:** As opposed to configuring an auto-destroy run for a specific date and time, this setting _persists_ after queueing auto-destroy runs. + +If you configure a workspace to auto-destroy its infrastructure when inactive, any run that updates Terraform state further delays the scheduled auto-destroy time by the length of your designated timeframe. + +To schedule an auto-destroy run after a period of workspace inactivity: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to destroy. +2. Choose **Settings** from the sidebar, then **Destruction and Deletion**. +3. Under **Automatically destroy**, click **Set up auto-destroy**. +4. Click the **Destroy if inactive** toggle. +5. Select or customize a desired timeframe of inactivity. +6. Click **Confirm auto-destroy**. + +When configured for the first time, the auto-destroy duration setting displays the scheduled date and time that HCP Terraform will perform the auto-destroy run. +Subsequent auto-destroy runs and Terraform runs that update state both update the next scheduled auto-destroy date. + +After HCP Terraform completes a manual or automatic destroy run, it waits until further state updates to schedule a new auto-destroy run. + +To remove your workspace's auto-destroy run: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to disable the auto-destroy run for. +2. Choose **Settings** from the sidebar, then **Destruction and Deletion**. +3. Under **Auto-destroy settings**, click **Edit** to change the auto-destroy settings. +4. Click **Remove**. + +When you move a workspace to a different project, it inherits the auto-destroy settings from the new project. If you configured the workspace to override the previous project's auto-destroy settings, it retains the override configuration in the new project. + +## Delete Workspace + +Terraform does not automatically destroy managed infrastructure when you delete a workspace. + +After you delete the workspace and its state file, Terraform can _no longer track or manage_ that infrastructure. You must manually delete or [import](/terraform/cli/commands/import) any remaining resources into another Terraform workspace. + +By default, [workspace administrators](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) can only delete unlocked workspaces that are not managing any infrastructure. Organization owners can force delete a workspace to override these protections. Organization owners can also configure the [organization's settings](/terraform/enterprise/users-teams-organizations/organizations#general) to let workspace administrators force delete their own workspaces. + +## Data Retention Policies + + +Data retention policies are exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +Define configurable data retention policies for workspaces to help reduce object storage consumption. You can define a policy that allows Terraform to _soft delete_ the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform can automatically delete the object after a set number of days. + +Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection grace period elapses, you can still restore an object using the APIs described in the [configuration version documentation](/terraform/enterprise/api-docs/configuration-versions) and [state version documentation](/terraform/enterprise/api-docs/state-versions). After the garbage collection grace period elapses, Terraform permanently deletes the archivist storage. + +The [organization policy](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) is the default policy applied to workspaces, but members of individual workspaces can override the policy for their workspaces. + +The workspace policy always overrides the organization policy. A workspace admin can set or override the following data retention policies: + +- **Organization default policy** +- **Do not auto-delete** +- **Auto-delete data** + +Setting the data retention policy to **Organization default policy** disables the other data retention policy settings. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/index.mdx new file mode 100644 index 0000000000..e57f67d8f4 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/index.mdx @@ -0,0 +1,212 @@ +--- +page_title: Workspaces settings in Terraform Enterprise +description: >- + Learn how to configure workspace settings for notifications, permissions, + health, locking, policies, run triggers, SSH keys, team access, version + control, and deletion. +source: terraform-docs-common +--- + +# Workspace settings + +You can change a workspace’s settings after creation. Workspace settings are separated into several pages. + +- [General](#general): Settings that determine how the workspace functions, including its name, description, associated project, Terraform version, and execution mode. +- [Health](/terraform/enterprise/workspaces/health): Settings that let you configure health assessments, including drift detection and continuous validation. +- [Locking](#locking): Locking a workspace temporarily prevents new plans and applies. +- [Notifications](#notifications): Settings that let you configure run notifications. +- [Policies](#policies): Settings that let you toggle between Sentinel policy evaluation experiences. +- [Run Triggers](#run-triggers): Settings that let you configure run triggers. Run triggers allow runs to queue automatically in your workspace when runs in other workspaces are successful. +- [SSH Key](#ssh-key): Set a private SSH key for downloading Terraform modules from Git-based module sources. +- [Team Access](#team-access): Settings that let you manage which teams can view the workspace and use it to provision infrastructure. +- [Version Control](#version-control): Manage the workspace’s VCS integration. +- [Destruction and Deletion](#destruction-and-deletion): Remove a workspace and the infrastructure it manages. + +Changing settings requires admin access to the relevant workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **API:** See the [Update a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#update-a-workspace) (`PATCH /organizations/:organization_name/workspaces/:name`). + +## General + +General settings let you change a workspace's name, description, the project it belongs to, and details about how Terraform runs operate. After changing these settings, click **Save settings** at the bottom of the page. + +### ID + +Every workspace has a unique ID that you cannot change. You may need to reference the workspace's ID when using the [HCP Terraform API](/terraform/enterprise/api-docs). + +Click the icon beside the ID to copy it to your clipboard. + +### Name + +The display name of the workspace. + +!> **Warning:** Some API calls refer to a workspace by its name, so changing the name may break existing integrations. + +### Project + +The [project](/terraform/enterprise/projects) that this workspace belongs to. Changing the workspace's project can change the read and write permissions for the workspace and which users can access it. + +To move a workspace, you must have the "Manage all Projects" organization permission or explicit team admin privileges on both the source and destination projects. Remember that moving a workspace to another project may affect user visibility for that project's workspaces. Refer to [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) for details on workspace access. + +### Description (Optional) + +Enter a brief description of the workspace's purpose or types of infrastructure. + +### Execution Mode + +Whether to use HCP Terraform as the Terraform execution platform for this workspace. + +By default, HCP Terraform uses an organization's [default execution mode](/terraform/enterprise/users-teams-organizations/organizations#organization-settings) to choose the execution platform for a workspace. Alternatively, you can instead choose a custom execution mode for a workspace. + +Specifying the "Remote" execution mode instructs HCP Terraform to perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more. + +To disable remote execution for a workspace, change its execution mode to "Local". This mode lets you perform Terraform runs locally with the [CLI-driven run workflow](/terraform/enterprise/run/cli). The workspace will store state, which Terraform can access with the [CLI integration](/terraform/cli/cloud). HCP Terraform does not evaluate workspace variables or variable sets in local execution mode. + +If you instead need to allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure, consider using [HCP Terraform agents](/terraform/cloud-docs/agents). By deploying a lightweight agent, you can establish a simple connection between your environment and HCP Terraform. + +Changing your workspace's execution mode after a run has already been planned will cause the run to error when it is applied. + +To minimize the number of runs that error when changing your workspace's execution mode, you should: + +1. Disable [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply) if you have it enabled. +2. Complete any runs that are no longer in the [pending stage](/terraform/enterprise/run/states#the-pending-stage). +3. [Lock](/terraform/enterprise/workspaces/settings#locking) your workspace to prevent any new runs. +4. Change the execution mode. +5. Enable [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply), if you had it enabled before changing your execution mode. +6. [Unlock](/terraform/enterprise/workspaces/settings#locking) your workspace. + + + + +### Auto-apply + +Whether or not HCP Terraform should automatically apply a successful Terraform plan. If you choose manual apply, an operator must confirm a successful plan and choose to apply it. + +The main auto-apply setting affects runs created by the HCP Terraform user interface, API, CLI, and version control webhooks. HCP Terraform also has a separate setting for runs created by [run triggers](/terraform/enterprise/workspaces/settings/run-triggers) from another workspace. + +Auto-apply has the following exception: + +- Plans queued by users without permission to apply runs for the workspace must be approved by a user who does have permission. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Terraform Version + +The Terraform version to use for all operations in the workspace. The default value is whichever release was current when HCP Terraform created the workspace. You can also update a workspace's Terraform version to an exact version or a valid [version constraint](/terraform/language/expressions/version-constraints). + +> **Hands-on:** Try the [Upgrade Terraform Version in HCP Terraform](/terraform/tutorials/cloud/cloud-versions) tutorial. + +-> **API:** You can specify a Terraform version when you [create a workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) with the API. + +### Terraform Working Directory + +The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. Defaults to the root of the configuration directory. + +HCP Terraform will change to this directory before starting a Terraform run, and will report an error if the directory does not exist. + +Setting a working directory creates a default filter for automatic run triggering, and sometimes causes CLI-driven runs to upload additional configuration content. + +#### Default Run Trigger Filtering + +In VCS-backed workspaces that specify a working directory, HCP Terraform assumes that only changes within that working directory should trigger a run. You can override this behavior with the [Automatic Run Triggering](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering) settings. + +#### Parent Directory Uploads + +If a working directory is configured, HCP Terraform always expects the complete shared configuration directory to be available, since the configuration might use local modules from outside its working directory. + +In [runs triggered by VCS commits](/terraform/enterprise/run/ui), this is automatic. In [CLI-driven runs](/terraform/enterprise/run/cli), Terraform's CLI sometimes uploads additional content: + +- When the local working directory _does not match_ the name of the configured working directory, Terraform assumes it is the root of the configuration directory, and uploads only the local working directory. +- When the local working directory _matches_ the name of the configured working directory, Terraform uploads one or more parents of the local working directory, according to the depth of the configured working directory. (For example, a working directory of `production` is only one level deep, so Terraform would upload the immediate parent directory. `consul/production` is two levels deep, so Terraform would upload the parent and grandparent directories.) + +If you use the working directory setting, always run Terraform from a complete copy of the configuration directory. Moving one subdirectory to a new location can result in unexpected content uploads. + +### Remote State Sharing + +Which other workspaces within the organization can access the state of the workspace during [runs managed by HCP Terraform](/terraform/enterprise/run/remote-operations#remote-operations). The [`terraform_remote_state` data source](/terraform/language/state/remote-state-data) relies on state sharing to access workspace outputs. + +- If "Share state globally" is enabled, all other workspaces within the organization can access this workspace's state during runs. +- If global sharing is turned off, you can specify a list of workspaces within the organization that can access this workspace's state; no other workspaces will be allowed. + + The workspace selector is searchable; if you don't initially see a workspace you're looking for, type part of its name. + +By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. We recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other. To configure remote state sharing, a user must have read access for the destination workspace. If a user does not have access to the destination workspace due to scoped project or workspace permissions, they will not have complete visibility into the list of other workspace that can access its state. + +-> **Note:** The default access permissions for new workspaces in HCP Terraform changed in April 2021. Workspaces created before this change default to allowing global access within their organization. These workspaces can be changed to more restrictive access at any time. Terraform Enterprise administrators can choose whether new workspaces on their instances default to global access or selective access. + +### User Interface + +Select the user experience for displaying plan and apply details. + +The default experience is _Structured Run Output_, which displays your plan and apply results in a human-readable format. This includes nodes that you can expand to view details about each resource and any configured output. + +The Console UI experience is the traditional Terraform experience, where live text logging is streamed in real time to the UI. This experience most closely emulates the CLI output. + +~> **Note:** Your workspace must be configured to use a Terraform version of 1.0.5 or higher for the Structured Run Output experience to be fully supported. Workspaces running versions from 0.15.2 may see partial functionality. Workspaces running versions below 0.15.2 will default to the "Console UI" experience regardless of the User Interface setting. + +## Locking + +~> **Important:** Unlike other settings, locks can also be managed by users with permission to lock and unlock the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If you need to prevent Terraform runs for any reason, you can lock a workspace. This prevents all applies (and many kinds of plans) from proceeding, and affects runs created via UI, CLI, API, and automated systems. To enable runs again, a user must unlock the workspace. + +Two kinds of run operations can ignore workspace locking because they cannot affect resources or state and do not attempt to lock the workspace themselves: + +- Plan-only runs. +- The planning stages of [saved plan runs](/terraform/enterprise/run/modes-and-options.mdx#saved-plans). You can only _apply_ a saved plan if the workspace is unlocked, and applying that plan locks the workspace as usual. Terraform Enterprise does not yet support this workflow. + +Locking a workspace also restricts state uploads. In order to upload state, the workspace must be locked by the user who is uploading state. + +Users with permission to lock and unlock a workspace can't unlock a workspace which was locked by another user. Users with admin access to a workspace can force unlock a workspace even if another user has locked it. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Locks are managed with a single "Lock/Unlock/Force unlock ``" button. HCP Terraform asks for confirmation when unlocking. + +You can also manage the workspace's lock from the **Actions** menu. + +## Notifications + +The "Notifications" page allows HCP Terraform to send webhooks to external services whenever specific run events occur in a workspace. + +See [Run Notifications](/terraform/enterprise/workspaces/settings/notifications) for detailed information about configuring notifications. + +## Policies + +HCP Terraform offers two experiences for Sentinel policy evaluations. On the "Policies" page, you can adjust your **Sentinel Experience** settings to your preferred experience. By default, HCP Terraform enables the newest policy evaluation experience. + +To toggle between the two Sentinel policy evaluation experiences, click the **Enable the new Sentinel policy experience** toggle under the **Sentinel Experience** heading. HCP Terraform persists your changes automatically. If HCP Terraform is performing a run on a different page, you must refresh that page to see changes to your policy evaluation experience. + +## Run Triggers + +The "Run Triggers" page configures connections between a workspace and one or more source workspaces. These connections, called "run triggers", allow runs to queue automatically in a workspace on successful apply of runs in any of the source workspaces. + +See [Run Triggers](/terraform/enterprise/workspaces/settings/run-triggers) for detailed information about configuring run triggers. + +## SSH Key + +If a workspace's configuration uses [Git-based module sources](/terraform/language/modules/sources) to reference Terraform modules in private Git repositories, Terraform needs an SSH key to clone those repositories. The "SSH Key" page lets you choose which key it should use. + +See [Using SSH Keys for Cloning Modules](/terraform/enterprise/workspaces/settings/ssh-keys) for detailed information about this page. + +## Team Access + +The "Team Access" page configures which teams can perform which actions on a workspace. + +See [Managing Access to Workspaces](/terraform/enterprise/workspaces/settings/access) for detailed information. + +## Version Control + +The "Version Control" page configures an optional VCS repository that contains the workspace's Terraform configuration. Version control integration is only relevant for workspaces with [remote execution](#execution-mode) enabled. + +See [VCS Connections](/terraform/enterprise/workspaces/settings/vcs) for detailed information about this page. + +## Destruction and Deletion + +The **Destruction and Deletion** page allows [admin users](/terraform/enterprise/users-teams-organizations/permissions) to delete a workspace's managed infrastructure or delete the workspace itself. + +For details, refer to [Destruction and Deletion](/terraform/enterprise/workspaces/settings/deletion) for detailed information about this page. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/notifications.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/notifications.mdx new file mode 100644 index 0000000000..2c9b97b15e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/notifications.mdx @@ -0,0 +1,130 @@ +--- +page_title: Workspace notifications in Terraform Enterprise +description: >- + Use webhooks to notify external systems about run progress and other events in + Terraform Enterprise. Learn to create and enable workspace notifications. +source: terraform-docs-common +--- + +# Workspace notifications + +HCP Terraform can use webhooks to notify external systems about run progress and other events. Each workspace has its own notification settings and can notify up to 20 destinations. + +-> **Note:** [Speculative plans](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) and workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) do not support notifications. + +Configuring notifications requires admin access to the workspace. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **API:** Refer to [Notification Configuration APIs](/terraform/enterprise/api-docs/notification-configurations). + +## Viewing and Managing Notification Settings + +To add, edit, or delete notifications for a workspace, go to the workspace and click **Settings > Notifications**. The **Notifications** page appears, showing existing notification configurations. + +## Creating a Notification Configuration + +A notification configuration specifies a destination URL, a payload type, and the events that should generate a notification. To create a notification configuration: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select the workspace you want to configure notifications for. + +2. Click **Settings**, then **Notifications**. + +3. Click **Create a Notification**. The **Create a Notification** form appears. + +4. Configure the notifications: + +- **Destination:** HCP Terraform can deliver either a generic payload or a payload formatted specifically for Slack, Microsoft Teams, or Email. Refer to [Notification Payloads](#notification-payloads) for details. + +- **Name:** A display name for this notification configuration. + +- **Webhook URL** This URL is only available for generic, Slack, and Microsoft Teams webhooks. The webhook URL is the destination for the webhook payload. This URL must accept HTTP or HTTPS `POST` requests and should be able to use the chosen payload type. For details, refer to Slack's documentation on [creating an incoming webhook](https://api.slack.com/messaging/webhooks#create_a_webhook) and Microsoft's documentation on [creating a workflow from a channel in teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-channel-in-teams-242eb8f2-f328-45be-b81f-9817b51a5f0e). + +- **Token** (Optional) This notification is only available for generic webhooks. A token is an arbitrary secret string that HCP Terraform will use to sign its notification webhooks. Refer to [Notification Authenticity][inpage-hmac] for details. You cannot view the token after you save the notification configuration. + +- **Email Recipients** This notification is only available for emails. Select users that should receive notifications. + +- **Workspace Events**: HCP Terraform can send notifications for all events or only for specific events. The following events are available: + + - **Drift**: HCP Terraform detected configuration drift. This notification is only available if you enable [health assessments](/terraform/enterprise/workspaces/health) for the workspace. + - **Check Failure:** HCP Terraform detected one or more failed continuous validation checks. This notification is only available if you enable health assessments for the workspace. + - **Health Assessment Fail**: A health assessment failed. This notification is only available if you enable health assessments for the workspace. Health assessments fail when HCP Terraform cannot perform drift detection, continuous validation, or both. The notification does not specify the cause of the failure, but you can use the [Assessment Result](/terraform/enterprise/api-docs/assessment-results) logs to help diagnose the issue. + - **Auto destroy reminder**: Sends reminders 12 and 24 hours before a scheduled auto destroy run. + - **Auto destroy results**: HCP Terraform performed an auto destroy run in the workspace. Reports both successful and errored runs. + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +- **Run Events:** HCP Terraform can send notifications for all events or only for specific events. The following events are available: + - **Created**: A run begins and enters the [Pending stage](/terraform/enterprise/run/states#the-pending-stage). + - **Planning**: A run acquires the lock and starts to execute. + - **Needs Attention**: A plan has changes and Terraform requires user input to continue. This event may include approving the plan or a [policy override](/terraform/enterprise/run/states#the-policy-check-stage). + - **Applying**: A run enters the [Apply stage](/terraform/enterprise/run/states#the-apply-stage), where Terraform makes the infrastructure changes described in the plan. + - **Completed**: A run completed successfully. + - **Errored**: A run terminated early due to error or cancellation. + +4. Click **Create a notification**. + +## Enabling and Verifying a Configuration + +To enable or disable a configuration, toggle the **Enabled/Disabled** switch on its detail page. HCP Terraform will attempt to verify the configuration for generic and slack webhooks by sending a test message, and will enable the notification configuration if the test succeeds. + +For a verification to be successful, the destination must respond with a `2xx` HTTP code. If verification fails, HCP Terraform displays the error message and the configuration will remain disabled. + +For both successful and unsuccessful verifications, click the **Last Response** box to view more information about the verification results. You can also send additional test messages with the **Send a Test** link. + +## Notification Payloads + +### Slack + +Notifications to Slack will contain the following information: + +- The run's workspace (as a link) +- The HCP Terraform username and avatar of the person that created the run +- The run ID (as a link) +- The reason the run was queued (usually a commit message or a custom message) +- The time the run was created +- The event that triggered the notification and the time that event occurred + +### Microsoft Teams + +Notifications to Microsoft Teams contain the following information: + +- The run's workspace (as a link) +- The HCP Terraform username and avatar of the person that created the run +- The run ID +- A link to view the run +- The reason the run was queued (usually a commit message or a custom message) +- The time the run was created +- The event that triggered the notification and the time that event occurred + +### Email + +Email notifications will contain the following information: + +- The run's workspace (as a link) +- The run ID (as a link) +- The event that triggered the notification, and if the run needs to be acted upon or not + +### Generic + +A generic notification will contain information about a run and its state at the time the triggering event occurred. The complete generic notification payload is described in the [API documentation][generic-payload]. + +[generic-payload]: /terraform/enterprise/api-docs/notification-configurations#notification-payload + +Some of the values in the payload can be used to retrieve additional information through the API, such as: + +- The [run ID](/terraform/enterprise/api-docs/run#get-run-details) +- The [workspace ID](/terraform/enterprise/api-docs/workspaces#list-workspaces) +- The [organization name](/terraform/enterprise/api-docs/organizations#show-an-organization) + +## Notification Authenticity + +[inpage-hmac]: #notification-authenticity + +Slack notifications use Slack's own protocols for verifying HCP Terraform's webhook requests. + +Generic notifications can include a signature for verifying the request. For notification configurations that include a secret token, HCP Terraform's webhook requests will include an `X-TFE-Notification-Signature` header, which contains an HMAC signature computed from the token using the SHA-512 digest algorithm. The receiving service is responsible for validating the signature. More information, as well as an example of how to validate the signature, can be found in the [API documentation](/terraform/enterprise/api-docs/notification-configurations#notification-authenticity). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/run-tasks.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/run-tasks.mdx new file mode 100644 index 0000000000..5831610aa2 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/run-tasks.mdx @@ -0,0 +1,129 @@ +--- +page_title: Terraform Enterprise run tasks +description: >- + Run tasks integrate third-party tools into the run lifecycle. Learn how to + create, delete, and associate run tasks with workspaces. +source: terraform-docs-common +--- + +[entitlement]: /terraform/enterprise/api-docs#feature-entitlements + +# Run tasks + +HCP Terraform run tasks let you directly integrate third-party tools and services at certain stages in the HCP Terraform run lifecycle. Use run tasks to validate Terraform configuration files, analyze execution plans before applying them, scan for security vulnerabilities, or perform other custom actions. + +Run tasks send data about a run to an external service at [specific run stages](#understanding-run-tasks-within-a-run). The external service processes the data, evaluates whether the run passes or fails, and sends a response to HCP Terraform. HCP Terraform then uses this response and the run task enforcement level to determine if a run can proceed. [Explore run tasks in the Terraform registry](https://registry.terraform.io/browse/run-tasks). + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +You can manage run tasks through the HCP Terraform UI or the [Run Tasks API](/terraform/enterprise/api-docs/run-tasks/run-tasks). + +> **Hands-on:** Try the [HCP Packer validation run task](/packer/tutorials/hcp/setup-hcp-terraform-run-task) tutorial. + +## Requirements + +**Terraform Version** - You can assign run tasks to workspaces that use a Terraform version of 1.1.9 and later. You can downgrade a workspace with existing runs to use a prior Terraform version without causing an error. However, HCP Terraform no longer triggers the run tasks during plan and apply operations. + +**Permissions** - To create a run task, you must have a user account with the [Manage Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#manage-run-tasks). To associate run tasks with a workspace, you need the [Manage Workspace Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) on that particular workspace. + +## Creating a Run Task + +Explore the full list of [run tasks in the Terraform Registry](https://registry.terraform.io/browse/run-tasks). + +Run tasks send an API payload to an external service. The API payload contains run-related information, including a callback URL, which the service uses to return a pass or fail status to HCP Terraform. + +For example, the [HCP Packer integration](/terraform/enterprise/integrations/run-tasks#hcp-packer-run-task) checks image artifacts within a Terraform configuration for validity. If the configuration references images marked as unusable (revoked), then the run task fails and provides an error message. + +To create a new run task: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace where you want to create a run task. + +2. Choose **Settings** from the sidebar, then **Run Tasks**. + +3. Click **Create a new run task**. The **Run Tasks** page appears. + +4. Enter the information about the run task to be configured: + + - **Enabled** (optional): Whether the run task will run across all associated workspaces. New tasks are enabled by default. + - **Name** (required): A human-readable name for the run task. This will be displayed in workspace configuration pages and can contain letters, numbers, dashes and underscores. + - **Endpoint URL** (required): The URL for the external service. Run tasks will POST the [run tasks payload](/terraform/enterprise/integrations/run-tasks#integration-details) to this URL. + - **Description** (optional): A human-readable description for the run task. This information can contain letters, numbers, spaces, and special characters. + - **HMAC key** (optional): A secret key that may be required by the external service to verify request authenticity. + +5. Click **Create run task**. The run task is now available within the organization, and you can associate it with one or more workspaces. + +### Global Run Tasks + +When you create a new run task, you can choose to apply it globally to every workspace in an organization. Your organization must have the `global-run-task` [entitlement][] to use global run tasks. + +1. Select the **Global** checkbox + +2. Choose when HCP Terraform should start the run task: + + - **Pre-plan**: Before Terraform creates the plan. + - **Post-plan**: After Terraform creates the plan. + - **Pre-apply**: Before Terraform applies a plan. + - **Post-apply**: After Terraform applies a plan. + +3. Choose an enforcement level: + + - **Advisory**: Run tasks can not block a run from completing. If the task fails, the run proceeds with a warning in the user interface. + - **Mandatory**: Failed run tasks can block a run from completing. If the task fails (including timeouts or unexpected remote errors), the run stops and errors with a warning in the user interface. + +## Associating Run Tasks with a Workspace + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, and choose **Workspaces** from the sidebar. + +2. Select the workspace that you want to associate with a run task. + +3. Open the **Settings** menu and select **Run Tasks**. + +4. Click the **+** next to the task you want to add to the workspace. + +5. Choose when HCP Terraform should start the run task: + + - **Pre-plan**: Before Terraform creates the plan. + - **Post-plan**: After Terraform creates the plan. + - **Pre-apply**: Before Terraform applies a plan. + - **Post-apply**: After Terraform applies a plan. + +6. Choose an enforcement level: + + - **Advisory**: Run tasks can not block a run from completing. If the task fails, the run will proceed with a warning in the UI. + - **Mandatory**: Run tasks can block a run from completing. If the task fails (including a timeout or unexpected remote error condition), the run will transition to an Errored state with a warning in the UI. + +7. Click **Create**. Your run task is now configured. + +## Understanding Run Tasks Within a Run + +Run tasks perform actions before and after, the [plan](/terraform/enterprise/run/states#the-plan-stage) and [apply](/terraform/enterprise/run/states#the-apply-stage) stages of a [Terraform run](/terraform/enterprise/run/remote-operations). Once all run tasks complete, the run ends based on the most restrictive enforcement level in each associated run task. + +For example, if a mandatory task fails and an advisory task succeeds, the run fails. If an advisory task fails, but a mandatory task succeeds, the run succeeds and proceeds to the apply stage. Regardless of the exit status of a task, HCP Terraform displays the status and any related message data in the UI. + +## Removing a Run Task from a Workspace + +Removing a run task from a workspace does not delete it from the organization. To remove a run task from a specific workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace where you want to remove a run task. + +2. Choose **Settings** from the sidebar, then **Run Tasks**. + +3. Click the ellipses (...) on the associated run task, and then click **Remove**. The run task will no longer be applied to runs within the workspace. + +## Deleting a Run Task + +You must remove a run task from all associated workspaces before you can delete it. To delete a run task: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace associated with a run task you want to delete. + +2. Choose **Settings** from the sidebar, then **Run Tasks**. + +3. Click the ellipses (...) next to the run task you want to delete, and then click **Edit**. + +4. Click **Delete run task**. + +You cannot delete run tasks that are still associated with a workspace. If you attempt this, you will see a warning in the UI containing a list of all workspaces that are associated with the run task. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/run-triggers.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/run-triggers.mdx new file mode 100644 index 0000000000..13bda16de0 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/run-triggers.mdx @@ -0,0 +1,51 @@ +--- +page_title: Terraform Enterprise run triggers +description: >- + Use run triggers to connect workspaces within your organization. Learn how to + view, create, and manage run triggers. +source: terraform-docs-common +--- + +# Run triggers + +> **Hands-on:** Try the [Connect Workspaces with Run Triggers](/terraform/tutorials/cloud/cloud-run-triggers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. + +HCP Terraform provides a way to connect your workspace to one or more workspaces within your organization, known as "source workspaces". These connections, called run triggers, allow runs to queue automatically in your workspace on successful apply of runs in any of the source workspaces. You can connect each workspace to up to 20 source workspaces. + +Run triggers are designed for workspaces that rely on information or infrastructure produced by other workspaces. If a Terraform configuration uses [data sources](/terraform/language/data-sources) to read values that might be changed by another workspace, run triggers let you explicitly specify that external dependency. + +-> **API:** See the [Run Triggers APIs](/terraform/enterprise/api-docs/run-triggers). + +## Viewing and Managing Run Triggers + +To add or delete a run trigger, navigate to the desired workspace and choose "Run Triggers" from the "Settings" menu: + +This takes you to the run triggers settings page, which shows any existing run triggers. Configuring run triggers requires admin access to the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) Admins are able to delete any of their workspace’s run triggers from this page. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Creating a Run Trigger + +Creating run triggers requires admin access to the workspace. You must also have permission to read runs for the source workspace you wish to connect to. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Under the "Source Workspaces" section, select the workspace you would like to connect as your source and click "Add workspace". You now have a run trigger established with your source workspace. Any run from that source workspace which applies successfully will now cause a new run to be queued in your workspace. + +## Run Triggers Auto-Apply Setting + +Runs initiated by a run trigger do not auto-apply unless you enable the **Auto-apply run triggers** setting. This setting operates independently of the primary workspace [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply) setting. + +## Interacting with Run Triggers + +Runs which are queued in your workspace through a run trigger will include extra information in their run details section. This includes links to the source workspace and the successfully applied run that activated the run trigger. + +The source workspace includes a message in the [plan](/terraform/docs/glossary#plan-noun-1-) and [apply](/terraform/docs/glossary#apply-noun-) run details that specifies the workspaces where HCP Terraform automatically starts a run. + +## Using a Remote State Data Source + +A common way to share information between workspaces is the [`terraform_remote_state` data source](/terraform/language/state/remote-state-data), which allows a Terraform configuration to access a source workspace's root-level [outputs](/terraform/language/values/outputs). + +Before other workspaces can read the outputs of a workspace, it must be configured to allow access. For more information about cross-workspace state access in HCP Terraform, see [Terraform State in HCP Terraform](/terraform/enterprise/workspaces/state). + +~> **Important:** We recommend using the [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) in the [HCP Terraform/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) to access remote state outputs in HCP Terraform or Terraform Enterprise. The `tfe_outputs` data source is more secure because it does not require full access to workspace state to fetch outputs. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/ssh-keys.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/ssh-keys.mdx new file mode 100644 index 0000000000..d2a9fde19e --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/ssh-keys.mdx @@ -0,0 +1,63 @@ +--- +page_title: Use SSH Keys to clone modules in Terraform Enterprise +description: >- + Learn how to configure the SSH keys that Terraform uses to pull modules from + private Git repositories. Learn to add, delete, and assign keys to workspaces. +source: terraform-docs-common +--- + +# Use SSH Keys for cloning modules + +Terraform configurations can pull in Terraform modules from [a variety of different sources](/terraform/language/modules/sources), and private Git repositories are a common source for private modules. + +-> **Note:** The [private module registry](/terraform/enterprise/registry) is an easier way to manage private Terraform modules in HCP Terraform, and doesn't require setting SSH keys for workspaces. The rest of this page only applies to configurations that fetch modules directly from a private Git repository. + +To access a private Git repository, Terraform either needs login credentials (for HTTPS access) or an SSH key. HCP Terraform can store private SSH keys centrally, and you can easily use them in any workspace that clones modules from a Git server. + +-> **Note:** SSH keys for cloning Terraform modules from Git repos are only used during Terraform runs. They are managed separately from any [keys used for bringing VCS content into HCP Terraform](/terraform/enterprise/vcs#ssh-keys). + +HCP Terraform manages SSH keys used to clone Terraform modules at the organization level, and allows multiple keys to be added for the organization. You can add or delete keys via the organization's settings. Once a key is uploaded, the text of the key is not displayed to users. + +To assign a key to a workspace, go to its settings and choose a previously added key from the drop-down menu on Integrations under "SSH Key". Each workspace can only use one SSH key. + +-> **API:** See the [SSH Keys API](/terraform/enterprise/api-docs/ssh-keys) and [Assign an SSH Key to a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#assign-an-ssh-key-to-a-workspace).
+**Terraform:** See the `tfe` provider's [`tfe_ssh_key`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/ssh_key) resource. + +## Adding Keys + +To add a key: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and choose the organization you want to add a key to. +2. Choose **Settings** from the sidebar, then **SSH Keys**. This page has a form for adding new keys and a list of existing keys. +3. Obtain a PEM formatted SSH keypair that HCP Terraform can use to download modules during a Terraform run. You might already have an appropriate key. If not, create one on a secure workstation and distribute the public key to your VCS provider(s). Do not use or generate a key that has a passphrase. Git is running non-interactively and cannot prompt for it. + + The exact command to create a PEM formatted SSH keypair depends on your operating system. The following example command creates a `service_terraform` file with the private key and a `service_terraform.pub` file with the public key. + + ```bash + ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise" + ``` +4. Enter a name for the key in the **Name** field. Choose something identifiable. Keys are only listed by name. HCP Terraform retains the text of each private key, but never displays it for any purpose. +5. Paste the text of the private key in the **Private SSH Key** field. +6. Click **Add Private SSH Key**. + +The new key appears in the list of keys on the page. + +If you upload an invalid SSH key, upload the correct key and push a new commit for the new key to take effect. + +## Deleting Keys + +Before deleting a key, you should assign a new key to any workspaces that are using it. Otherwise workspaces using the deleted key can no longer clone modules from private repositories. This inability might cause Terraform runs to fail. + +To delete a key: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and choose the organization you want to delete a key from. +2. Choose **Settings** from the sidebar, then **SSH Keys**. +3. Find the key you want to delete and click **Delete**. + +## Assigning Keys to Workspaces + +To assign a key to a workspace, navigate to that workspace's page and choose "SSH Key" from the "Settings" menu. + +Select a named key from the "SSH Key" dropdown menu, then click the "Update SSH key" button. + +In subsequent runs, HCP Terraform will use the selected SSH key in this workspace when cloning modules from Git. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/vcs.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/vcs.mdx new file mode 100644 index 0000000000..a1e34e5a58 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/settings/vcs.mdx @@ -0,0 +1,127 @@ +--- +page_title: Configure workspace VCS connections in Terraform Enterprise +description: >- + Learn how to use the Terraform Enterprise UI to connect a workspace to a + version control system (VCS) repository that contains a Terraform + configuration. +source: terraform-docs-common +--- + +# Configure workspace VCS connections + +You can connect any HCP Terraform [workspace](/terraform/enterprise/workspaces) to a version control system (VCS) repository that contains a Terraform configuration. This page explains the workspace VCS connection settings in the HCP Terraform UI. + +Refer to [Terraform Configurations in HCP Terraform Workspaces](/terraform/enterprise/workspaces/configurations) for details on handling configuration versions and connected repositories. Refer to [Connecting VCS Providers](/terraform/enterprise/vcs) for a list of supported VCS providers and details about configuring VCS access, viewing VCS events, etc. + +## API + +You can use the [Update a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#update-a-workspace) in the Workspaces API to change one or more VCS settings. We also recommend using this endpoint to automate changing VCS connections for many workspaces at once. For example, when you move a VCS server or remove a deprecated API version. + +## Version Control Settings + +To change a workspace's VCS settings: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and find the workspace you want to update. +2. Choose **Settings** from the sidebar, then **Version Control**. +3. Choose the settings you want, then click **Update VCS settings**. + +You can update the following types of VCS settings for the workspace. + +### VCS Connection + +You can take one of the following actions: + +- To add a new VCS connection, click **Connect to version control**. Select **Version control workflow** and follow the steps to [select a VCS provider and repository](/terraform/enterprise/workspaces/create#create-a-workspace). +- To edit an existing VCS connection, click **Change source**. Choose the **Version control workflow** and follow the steps to [select VCS provider and repository](/terraform/enterprise/workspaces/create#create-a-workspace). +- To remove the VCS connection, click **Change source**. Select either the **CLI-driven workflow** or the **API-driven workflow**, and click **Update VCS settings**. The workspace is no longer connected to VCS. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Terraform Working Directory + +Specify the directory where Terraform will execute runs. This defaults to the root directory in your repository, but you may want to specify another directory if you have directories for multiple different Terraform configurations within the same repository. For example, if you had one `staging` directory and one `production` directory. + +A working directory is required when you use [trigger prefixes](#automatic-run-triggering). + +### Apply Method + +Choose a workflow for Terraform runs. + +- **Auto apply:** Terraform will apply changes from successful plans without prompting for approval. A push to the default branch of your repository will trigger a plan and apply cycle. You may want to do this in non-interactive environments, like continuous deployment workflows. + + !> **Warning:** If you choose auto apply, make sure that no one can change your infrastructure outside of your automated build pipeline. This reduces the risk of configuration drift and unexpected changes. + +- **Manual apply:** Terraform will ask for approval before applying changes from a successful plan. A push to the default branch of your repository will trigger a plan, and then Terraform will wait for confirmation. + +### Automatic Run Triggering + +HCP Terraform uses your VCS provider's API to retrieve the changed files in your repository. You can choose one of the following options to specify which changes trigger Terraform runs. + +#### Always trigger runs + +This option instructs Terraform to begin a run when changes are pushed to any file within the repository. This can be useful for repositories that do not have multiple configurations but require a working directory for some other reason. However, we do not recommend this approach for true monorepos, as it queues unnecessary runs and slows down your ability to provision infrastructure. + +#### Only trigger runs when files in specified paths change + +This option instructs Terraform to begin new runs only for changes that affect specified files and directories. This behavior also applies to [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans) on pull requests. + +You can use trigger patterns and trigger prefixes in the **Add path** field to specify groups of files and directories. + +- **Trigger Patterns:** (Recommended) Use glob patterns to specify the files that should trigger a new run. For example, `/submodule/**/*.tf`, specifies all files with the `.tf` extension that are nested below the `submodule` directory. You can also use more complex patterns like `/**/networking/**/*`, which specifies all files that have a `networking` folder in their file path. (e.g., `/submodule/service-1/networking/private/main.tf`). Refer to [Glob Patterns for Automatic Run Triggering](#glob-patterns-for-automatic-run-triggering) for details. +- **Trigger Prefixes:** HCP Terraform will queue runs for changes in any of the specified trigger directories matching the provided prefixes (including the working directory). For example, if you use a top-level `modules` directory to share Terraform code across multiple configurations, changes to the shared modules are relevant to every workspace that uses that repository. You can add `modules` as a trigger directory for each workspace to track changes to shared code. + +-> **Note:** HCP Terraform triggers runs on all attached workspaces if it does not receive a list of changed files or if that list is too large to process. When this happens, HCP Terraform may show several runs with completed plans that do not result in infrastructure changes. + +#### Trigger runs when a git tag is published + +This option instructs Terraform to begin new runs only for changes that have a specific tag format. + +The tag format can be chosen between the following options: + +- **Semantic Versioning:** It matches tags in the popular [SemVer format](https://semver.org/). For example, `0.4.2`. +- **Version contains a prefix:** It matches tags which have an additional prefix before the [SemVer format](https://semver.org/). For example, `version-0.4.2`. +- **Version contains a suffix:** It matches tags which have an additional suffix after the [SemVer format](https://semver.org/). For example `0.4.2-alpha`. +- **Custom Regular Expression:** You can define your own regex for HCP Terraform to match against tags. + +You must include an additional `\` to escape the regex pattern when you manage your workspace with the [hashicorp/tfe provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/workspace#tags_regex) and trigger runs through matching git tags. Refer to [Terraform escape sequences](/terraform/language/expressions/strings#escape-sequences) for more details. + +| Tag Format | Regex Pattern | Regex Pattern (Escaped) | +| ----------------------------- | --------------- | ----------------------- | +| **Semantic Versioning** | `^\d+.\d+.\d+$` | `^\\d+.\\d+.\\d+$` | +| **Version contains a prefix** | `\d+.\d+.\d+$` | `\\d+.\\d+.\\d+$` | +| **Version contains a suffix** | `^\d+.\d+.\d+` | `^\\d+.\\d+.\\d+` | + +HCP Terraform triggers runs for all tags matching this pattern, regardless of the value in the [VCS Branch](#vcs-branch) setting. + +### VCS Branch + +This setting designates which branch of the repository HCP Terraform should use when the workspace is set to [Always Trigger Runs](#always-trigger-runs) or [Only trigger runs when files in specified paths change](#only-trigger-runs-when-files-in-specified-paths-change). If you leave this setting blank, HCP Terraform uses the repository's default branch. If the workspace is set to trigger runs when a [git tag is published](#trigger-runs-when-a-git-tag-is-published), all tags will trigger runs, regardless of the branch specified in this setting. + +### Automatic Speculative Plans + +Whether to perform [speculative plans on pull requests](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) to the connected repository, to assist in reviewing proposed changes. Automatic speculative plans are enabled by default, but you can disable them for any workspace. + +### Include Submodules on Clone + +Select **Include submodules on clone** to recursively clone all of the repository's Git submodules when HCP Terraform fetches a configuration. + +-> **Note:** The [SSH key for cloning Git submodules](/terraform/enterprise/vcs#ssh-keys) is set in the VCS provider settings for the organization and is not related to the workspace's SSH key for Terraform modules. + +## Glob Patterns for Automatic Run Triggering + +We support `glob` patterns to describe a set of triggers for automatic runs. Refer to [trigger patterns](#only-trigger-runs-when-files-in-specified-paths-change) for details. + +Supported wildcards: + +- `*` Matches zero or more characters. +- `?` Matches one or more characters. +- `**` Matches directories recursively. + +The following examples demonstrate how to use the supported wildcards: + +- `/**/*` matches every file in every directory +- `/module/**/*` matches all files in any directory below the `module` directory +- `/**/networking/*` matches every file that is inside any `networking` directory +- `/**/networking/**/*` matches every file that has `networking` directory on its path +- `/**/*.tf` matches every file in any directory that has the `.tf` extension +- `/submodule/*.???` matches every file inside `submodule` directory which has three characters long extension. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/state.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/state.mdx new file mode 100644 index 0000000000..4b070799df --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/state.mdx @@ -0,0 +1,257 @@ +--- +page_title: Manage workspace state in Terraform Enterprise +description: >- + Workspaces have their own separate state data. Learn how Terraform Enterprise + uses state and how to access state from across workspaces. +source: terraform-docs-common +--- + +# Manage workspace state + +Each HCP Terraform workspace has its own separate state data, used for runs within that workspace. + +-> **API:** See the [State Versions API](/terraform/enterprise/api-docs/state-versions). + +## State Usage in Terraform Runs + +In [remote runs](/terraform/enterprise/run/remote-operations), HCP Terraform automatically configures Terraform to use the workspace's state; the Terraform configuration does not need an explicit backend configuration. (If a backend configuration is present, it will be overridden.) + +In local runs (available for workspaces whose execution mode setting is set to "local"), you can use a workspace's state by configuring the [CLI integration](/terraform/cli/cloud) and authenticating with a user token that has permission to read and write state versions for the relevant workspace. When using a Terraform configuration that references outputs from another workspace, the authentication token must also have permission to read state outputs for that workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + + + +During an HCP Terraform run, Terraform incrementally creates intermediate state versions and marks them as finalized once it uploads the state content. + +When a workspace is unlocked, HCP Terraform selects the latest state and sets it as the current state version, deletes all other intermediate state versions that were saved as recovery snapshots for the duration of the lock, and discards all pending intermediate state versions that were superseded by newer state versions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + + + +## State Versions + +In addition to the current state, HCP Terraform retains historical state versions, which can be used to analyze infrastructure changes over time. + +You can view a workspace's state versions from its **States** tab. Each state in the list indicates which run and which VCS commit (if applicable) it was associated with. Click a state in the list for more details, including a diff against the previous state and a link to the raw state file. + + + +## Managed Resources Count + +-> **Note:** A managed resources count for each organization is available in your organization's settings. + +Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces. + +HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. Each [resource](/terraform/language/resources/syntax) in the state equals one managed resource. HCP Terraform includes resources in modules and each resource instance created with the `count` or `for_each` meta-arguments. For example, `"aws_instance" "servers" { count = 10 }` creates ten separate managed resources in state. HCP Terraform does not include [data sources](/terraform/language/data-sources) in the count. + +### Examples - Managed Resources + +The following Terraform state excerpt describes a `random` resource. HCP Terraform counts `random` as one managed resource because `“mode”: “managed”`. + +```json +"resources": [ +{ + "mode": "managed", + "type": "random_pet", + "name": "random", + "provider": "provider[\"registry.terraform.io/hashicorp/random\"]", + "instances": [ + { + "schema_version": 0, + "attributes": { + "id": "puma", + "keepers": null, + "length": 1, + "prefix": null, + "separator": "-" + }, + "sensitive_attributes": [] + } + ] + } +] +``` + +A single resource configuration block can describe multiple resource instances with the [`count`](/terraform/language/meta-arguments/count) or [`for_each`](/terraform/language/meta-arguments/for_each) meta-arguments. Each of these instances counts as a managed resource. + +The following example shows a Terraform state excerpt with 2 instances of a `aws_subnet` resource. HCP Terraform counts each instance of `aws_subnet` as a separate managed resource. + +```json +{ + "module": "module.vpc", + "mode": "managed", + "type": "aws_subnet", + "name": "public", + "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]", + "instances": [ + { + "index_key": 0, + "schema_version": 1, + "attributes": { + "arn": "arn:aws:ec2:us-east-2:561656980159:subnet/subnet-024b05c4fba9c9733", + "assign_ipv6_address_on_creation": false, + "availability_zone": "us-east-2a", + ##... + "private_dns_hostname_type_on_launch": "ip-name", + "tags": { + "Name": "-public-us-east-2a" + }, + "tags_all": { + "Name": "-public-us-east-2a" + }, + "timeouts": null, + "vpc_id": "vpc-0f693f9721b61333b" + }, + "sensitive_attributes": [], + "private": "eyJlMmJmYjczMC1lY2FhLTExZTYtOGY4OC0zNDM2M2JjN2M0YzAiOnsiY3JlYXRlIjo2MDAwMDAwMDAwMDAsImRlbGV0ZSI6MTIwMDAwMDAwMDAwMH0sInNjaGVtYV92ZXJzaW9uIjoiMSJ9", + "dependencies": [ + "data.aws_availability_zones.available", + "module.vpc.aws_vpc.this", + "module.vpc.aws_vpc_ipv4_cidr_block_association.this" + ] + }, + { + "index_key": 1, + "schema_version": 1, + "attributes": { + "arn": "arn:aws:ec2:us-east-2:561656980159:subnet/subnet-08924f16617e087b2", + "assign_ipv6_address_on_creation": false, + "availability_zone": "us-east-2b", + ##... + "private_dns_hostname_type_on_launch": "ip-name", + "tags": { + "Name": "-public-us-east-2b" + }, + "tags_all": { + "Name": "-public-us-east-2b" + }, + "timeouts": null, + "vpc_id": "vpc-0f693f9721b61333b" + }, + "sensitive_attributes": [], + "private": "eyJlMmJmYjczMC1lY2FhLTExZTYtOGY4OC0zNDM2M2JjN2M0YzAiOnsiY3JlYXRlIjo2MDAwMDAwMDAwMDAsImRlbGV0ZSI6MTIwMDAwMDAwMDAwMH0sInNjaGVtYV92ZXJzaW9uIjoiMSJ9", + "dependencies": [ + "data.aws_availability_zones.available", + "module.vpc.aws_vpc.this", + "module.vpc.aws_vpc_ipv4_cidr_block_association.this" + ] + } + ] +} +``` + +### Example - Excluded Data Source + +The following Terraform state excerpt describes a `aws_availability_zones` data source. HCP Terraform does not include `aws_availability_zones` in the managed resource count because `”mode”: “data”`. + +```json + "resources": [ + { + "mode": "data", + "type": "aws_availability_zones", + "name": "available", + "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]", + "instances": [ + { + "schema_version": 0, + "attributes": { + "all_availability_zones": null, + "exclude_names": null, + "exclude_zone_ids": null, + "filter": null, + "group_names": [ + "us-east-2" + ], + "id": "us-east-2", + "names": [ + "us-east-2a", + "us-east-2b", + "us-east-2c" + ], + "state": null, + "zone_ids": [ + "use2-az1", + "use2-az2", + "use2-az3" + ] + }, + "sensitive_attributes": [] + } + ] + } + ] +``` + + + +## State Manipulation + +Certain tasks (including importing resources, tainting resources, moving or renaming existing resources to match a changed configuration, and more) may require modifying Terraform state outside the context of a run, depending on which version of Terraform your HCP Terraform workspace is configured to use. + +Newer Terraform features like [`moved` blocks](/terraform/language/modules/develop/refactoring), [`import` blocks](/terraform/language/import), and the [`replace` option](/terraform/enterprise/run/modes-and-options#replacing-selected-resources) allow you to accomplish these tasks using the usual plan and apply workflow. However, if the Terraform version you're using doesn't support these features, you may need to fall back to manual state manipulation. + +Manual state manipulation in HCP Terraform workspaces, with the exception of [rolling back to a previous state version](#rolling-back-to-a-previous-state), requires the use of Terraform CLI, using the same commands as would be used in a local workflow (`terraform import`, `terraform taint`, etc.). To manipulate state, you must configure the [CLI integration](/terraform/cli/cloud) and authenticate with a user token that has permission to read and write state versions for the relevant workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +### Rolling Back to a Previous State + +You can rollback to a previous, known good state version using the HCP Terraform UI. Navigate to the state you want to rollback to and click the **Advanced** toggle button. This option requires that you have access to create new state and that you lock the workspace. It works by duplicating the state that you specify and making it the workspace's current state version. The workspace remains locked. To undo the rollback operation, rollback to the state version that was previously the latest state. + +-> **Note:** You can rollback to any prior state, but you should use caution because replacing state improperly can result in orphaned or duplicated infrastructure resources. This feature is provided as a convenient alternative to manually downloading older state and using state manipulation commands in the CLI to push it to HCP Terraform. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Accessing State from Other Workspaces + +-> **Note:** Provider-specific [data sources](/terraform/language/data-sources) are usually the most resilient way to share information between separate Terraform configurations. `terraform_remote_state` is more flexible, but we recommend using specialized data sources whenever it is convenient to do so. + +Terraform's built-in [`terraform_remote_state` data source](/terraform/language/state/remote-state-data) lets you share arbitrary information between configurations via root module [outputs](/terraform/language/values/outputs). + +HCP Terraform automatically manages API credentials for `terraform_remote_state` access during [runs managed by HCP Terraform](/terraform/enterprise/run/remote-operations#remote-operations). This means you do not usually need to include an API token in a `terraform_remote_state` data source's configuration. + +## Upgrading State + +You can upgrade a workspace's state version to a new Terraform version without making any configuration changes. To upgrade, we recommend the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to upgrade. +2. Run a [speculative plan](/terraform/enterprise/run/ui#testing-terraform-upgrades-with-speculative-plans) to test whether your configuration is compatible with the new Terraform version. You can run speculative plans with a Terraform version that is different than the one currently selected for the workspace. +3. Select **Settings > General** and select the desired new **Terraform Version**. +4. Click **+ New run** and then select **Allow empty apply** as the run type. An [empty apply](/terraform/enterprise/run/modes-and-options#allow-empty-apply) allows Terraform to apply a plan that produces no infrastructure changes. Terraform upgrades the state file version during the apply process. + +-> **Note:** If the desired Terraform version is incompatible with a workspace's existing state version, the run fails and HCP Terraform prompts you to run an apply with a compatible version first. Refer to the [Terraform upgrade guides](/terraform/language/upgrade-guides) for details about upgrading between versions. + +### Remote State Access Controls + +Remote state access between workspaces is subject to access controls: + +- Only workspaces within the same organization can access each other's state. +- The workspace whose state is being read must be configured to allow that access. State access permissions are configured on a workspace's [general settings page](/terraform/enterprise/workspaces/settings). There are two ways a workspace can allow access: + - Globally, to all workspaces within the same organization. + - Selectively, to a list of specific approved workspaces. + +By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. We recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other. + +-> **Note:** The default access permissions for new workspaces in HCP Terraform changed in April 2021. Workspaces created before this change defaulted to allowing global access within their organization. These workspaces can be changed to more restrictive access at any time on their [general settings page](/terraform/enterprise/workspaces/settings). Terraform Enterprise administrators can choose whether new workspaces on their instances default to global access or selective access. + +### Data Source Configuration + +To configure a `tfe_outputs` data source that references an HCP Terraform workspace, specify the organization and workspace in the `config` argument. + +You must still properly configure the `tfe` provider with a valid authentication token and correct permissions to HCP Terraform. + +```hcl +data "tfe_outputs" "vpc" { + config = { + organization = "example_corp" + workspaces = { + name = "vpc-prod" + } + } +} + +resource "aws_instance" "redis_server" { + # Terraform 0.12 and later: use the "outputs." attribute + subnet_id = data.tfe_outputs.vpc.outputs.subnet_id +} +``` + +-> **Note:** Remote state access controls do not apply when using the `tfe_outputs` data source. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/tags.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/tags.mdx new file mode 100644 index 0000000000..6617ddc9be --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/tags.mdx @@ -0,0 +1,94 @@ +--- +page_title: Create workspace tags +description: >- + Learn how to create tags for your workspaces so that you can organize + workspaces. Tagging workspaces also lets you sort and filter workspaces in the + UI. +source: terraform-docs-common +--- + +# Create workspace tags + +This topic describes how to create and attach tags to your workspaces. + +## Overview + +Tagging workspaces helps organization administrators organize, sort, and filter workspaces so that they can track resource consumption. For example, you could add a `cost-center` tag so that administrators can sort workspaces according to cost center. + +HCP Terraform stores tags as key-value pairs or as key-only tags. Key-only tags enable you to associate a single Terraform configuration file with several workspaces according to tag. Refer to the following topics in the Terraform CLI and configuration language documentation for additional information: + +- [`terraform{}.cloud{}.workspaces` reference](/terraform/language/terraform#terraform-cloud-workspaces) +- [Define connection settings](/terraform/cli/cloud/settings#define-connection-settings) + +### Reserved tags + +You can reserve a set of tag keys for each organization. Reserved tag keys appear as suggestions when people create tags for projects and workspaces so that you can use consistent terms for tags. Refer to [Create and manage reserved tags](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for additional information. + +### Single-value tags + +Your system may contain single-value tags created using Terraform v1.10 and older. You can migrate existing single-value tags to the key-value scheme. Refer to [Migrate single-value tags](#migrate-single-value-tags) for instructions. + +## Requirements + +- You must be member of a team with the **Write** permission group enabled for the workspace to create tags for a workspace. +- You must be member of a team with the **Admin** permission group enabled for the workspace to delete tags on a workspace. + +You cannot create tags for a workspace using the CLI. + +## Define tags + +1. Open your workspace. + +2. Click either the count link for the **Tags** label or **Manage Tags** in the **Tags** card on the right-sidebar to open the **Manage workspace tags** drawer. + +3. Click **+Add tag** and perform one of the following actions: + + - Specify a key-value pair: Lets you sort, filter, and search on either key or value. + - Specify a tag key and leave the **Value** field empty: Lets you sort, filter, and search on only the key name. + - Choose a reserved key from the suggested tag key list and specify a value: Ensures that you are using the key name consistently and lets you sort, filter, and search on either key or value. + - Choose a reserved key from the suggested tag key list and leave the **Value** field empty: Ensures that you are using the key name consistently and lets you sort, filter, and search on only the key name. + + Refer to [Tag syntax](#Tag-syntax) for information about supported characters. + +4. Tags inherited from the project appear in the **Inherited Tags** section. You can attach new key-value pairs to their projects to override inherited tags. Refer to [Manage projects](/terraform/enterprise/projects/manage) for additional information about using tags in projects. + + You cannot override reserved tag keys when the **Disable overrides** option is enabled. Refer to [Create and manage reserved tags](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for additional information. + + You can also click on tag links in the **Inherited Tags** section to view workspaces that use the same tag. + +5. Click **Save**. + +Tags that you create appear in the tags management screen in the organization settings. Refer to [Organizations](/terraform/enterprise/users-teams-organizations/organizations) for additional information. + +## Update tags + +1. Open your workspace. +2. Click either the count link for the **Tags** label or **Manage Tags** in the **Tags** card on the right-sidebar to open the **Manage workspace tags** drawer. +3. In the **Tags applied to this resource** section, modify a key, value, or both and click **Save**. + +## Migrate single-value tags + +You can use the API to convert existing single-value tags to key-value tags. You must have permissions in the workspace to perform the following task. Refer to [Requirements](#requirements) for additional information. + +Terraform v1.10 and older adds single-value workspace tags defined in the associated Terraform configuration to workspaces selected by the configuration. As result, your workspace may include duplicate tags. Refer to the [Terraform reference documentation](/terraform/language/terraform#terraform-cloud-workspaces) for additional information. + +### Re-create existing workspace tags as resource tags + +1. Send a `GET` request to the [`/organizations/:organization_name/tags`](/terraform/enterprise/api-docs/organization-tags#list-tags) endpoint to request all workspaces for your organization. The response may span several pages. +2. For each workspace, check the `tag-names` attribute for existing tags. +3. Send a `PATCH` request to the [`/workspaces/:workspace_id`](/terraform/enterprise/api-docs/workspaces#update-a-workspace) endpoint and include the `tag-binding` relationship in the request body for each workspace tag. + +### Delete single-value workspace tags + +1. Send a `GET` request to the [`/organizations/:organization_name/tags`](/terraform/enterprise/api-docs/organization-tags#list-tags) endpoint to request all workspaces for your organization. +2. Enumerate the external IDs for all tags. +3. Send a `DELETE` request to the [`/organizations/:organization_name/tags`](/terraform/enterprise/api-docs/organization-tags#delete-tags) endpoint to delete tags. + +## Tag syntax + +The following rules apply to tags: + +- Tags must be one or more characters. +- Tags have a 255 character limit. +- Tags can include letters, numbers, colons, hyphens, and underscores. +- For tags stored as key-value pairs, tag values are optional. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/variables/index.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/variables/index.mdx new file mode 100644 index 0000000000..22c1581891 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/variables/index.mdx @@ -0,0 +1,237 @@ +--- +page_title: Workspace variables in Terraform Enterprise +description: >- + Terraform Enterprise workspaces allow you to customize Terraform runs. Learn + how to use Terraform variables and environment variables. +source: terraform-docs-common +--- + +# Workspace variables + +HCP Terraform workspace variables let you customize configurations, modify Terraform's behavior, setup [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials), and store information like static provider credentials. + +You can set variables specifically for each workspace or you can create variable sets to reuse the same variables across multiple workspaces. For example, you could define a variable set of provider credentials and automatically apply it to all of the workspaces using that provider. You can use the command line to specify variable values for each plan or apply. Otherwise, HCP Terraform applies workspace variables to all runs within that workspace. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Types + +You can create both environment variables and Terraform variables in HCP Terraform. + +> **Hands-on:** Try the [Create and Use a Variable Sets](/terraform/tutorials/cloud-get-started/cloud-create-variable-set) and [Create Infrastructure](/terraform/tutorials/cloud-get-started/cloud-workspace-configure) tutorials to set environment and Terraform variables in HCP Terraform. + +### Environment variables + +HCP Terraform performs Terraform runs on disposable Linux worker VMs using a POSIX-compatible shell. Before running Terraform operations, HCP Terraform uses the `export` command to populate the shell with environment variables. + +Environment variables can store provider credentials and other data. Refer to your provider's Terraform Registry documentation for a full list of supported shell environment variables (e.g., authentication variables for [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#environment-variables), [Google Cloud Platform](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials), and [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#argument-reference)). Environment variables can also [modify Terraform's behavior](/terraform/cli/config/environment-variables). For example, `TF_LOG` enables detailed logs for debugging. + +#### Parallelism + +You can use the `TFE_PARALLELISM` environment variable when your infrastructure providers produce errors on concurrent operations or use non-standard rate limiting. The `TFE_PARALLELISM` variable sets the `-parallelism=` flag for `terraform plan` and `terraform apply` ([more about `parallelism`](/terraform/internals/graph#walking-the-graph)). Valid values are between 1 and 256, inclusive, and the default is `10`. HCP Terraform agents do not support `TFE_PARALLELISM`, but you can specify flags as environment variables directly via [`TF_CLI_ARGS_name`](/terraform/cli/config/environment-variables#tf-cli-args). In these cases, use `TF_CLI_ARGS_plan="-parallelism="` or `TF_CLI_ARGS_apply="-parallelism="` instead. + +!> **Warning:** We recommend reading and understanding [Terraform parallelism](https://support.hashicorp.com/hc/en-us/articles/10348130482451) prior to setting `TFE_PARALLELISM`. You can also contact HashiCorp support for direct advice. + +#### Dynamic credentials + +You can configure [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for certain providers using environment variables [at the workspace level](/terraform/enterprise/workspaces/variables/managing-variables#workspace-specific-variables) or using [variable sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +Dynamic credentials allows for using temporary per-run credentials and eliminates the need to manually rotate secrets. + +### Terraform variables + +Terraform variables refer to [input variables](/terraform/language/values/variables) that define parameters without hardcoding them into the configuration. For example, you could create variables that let users specify the number and type of Amazon Web Services EC2 instances they want to provision with a Terraform module. + +```hcl +variable "instance_count" { + description = "Number of instances to provision." + type = number + default = 2 +} +``` + +You can then reference this variable in your configuration. + +```hcl +module "ec2_instances" { + source = "./modules/aws-instance" + + instance_count = var.instance_count + ## ... +} +``` + +If a required input variable is missing, Terraform plans in the workspace will fail and print an explanation in the log. + +## Scope + +Each environment and Terraform variable can have one of the following scopes: + +| Scope | Description | Resources | +| ----------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Run-Specific | Apply to a specific run within a single workspace. | [Specify Run-Specific Variables](/terraform/enterprise/workspaces/variables/managing-variables#run-specific-variables) | +| Workspace-Specific | Apply to a single workspace. | [Create Workspace-Specific Variables](/terraform/enterprise/workspaces/variables/managing-variables#workspace-specific-variables), [Loading Variables from Files](/terraform/enterprise/workspaces/variables/managing-variables#loading-variables-from-files), [Workspace-Specific Variables API](/terraform/enterprise/api-docs/workspace-variables). | +| Workspace-Scoped Variable Set | Apply to multiple workspaces within the same organization. | [Create Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) and [Variable Sets API](/terraform/enterprise/api-docs/variable-sets) | +| Project-Scoped Variable Set | Automatically applied to all current and future workspaces within a project. | [Create Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) and [Variable Sets API](/terraform/enterprise/api-docs/variable-sets) | +| Global Variable Set | Automatically applied to all current and future workspaces within an organization. | [Create Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) and [Variable Sets API](/terraform/enterprise/api-docs/variable-sets) | + +## Variable set ownership + +Projects and organizations can both own variable sets. The owner of a variable set can determine the precedence of that set. + +Use organization-owned variable sets to share variables across multiple projects. Managing organization-owned variable sets [requires a higher permission level](/terraform/enterprise/workspaces/variables/managing-variables#permissions) because you can apply these sets to any project in your organization. + +Use project-owned variable sets to share variables across multiple workspaces within a single project. Project-owned variable sets only require permissions on the project itself, rather than organization-level permissions. + +Refer to [**Manage variable sets**](/terraform/enterprise/workspaces/variables/managing-variables#permissions) for more details on variable set permissions. + +## Precedence + +> **Hands On:** The [Manage Multiple Variable Sets in HCP Terraform](/terraform/tutorials/cloud/cloud-multiple-variable-sets) tutorial shows how to manage multiple variable sets and demonstrates variable precedence. + +There may be cases when a workspace contains conflicting variables of the same type with the same key. HCP Terraform marks overwritten variables in the UI. + +HCP Terraform prioritizes and overwrites conflicting variables according to the following precedence: + +### 1. Priority global variable sets + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a global variable set have precedence over all other variables with the same key. + +### 2. Priority project-scoped variable set owned by an organization + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a priority project-scoped variable set have precedence over variables with the same key set at a more specific scope. Prioritized variables sets owned by organizations take precedence over priority variable sets owned by projects. + +### 3. Priority workspace-scoped variable set owned by an organization + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in an organization-owned variable set scoped to a workspace have precedence over variables with the same key set at a more specific scope. Prioritized variables sets owned by organizations take precedence over sets owned by projects. + +### 4. Priority project-scoped variable set owned by a project + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a priority project-scoped variable set have precedence over variables with the same key set at a more specific scope. + +### 5. Priority workspace-scoped variable set owned by a project + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a priority workspace-scoped variable set have precedence over variables with the same key set at a more specific scope. + +### 6. Command line argument variables + +When using a CLI workflow, variables applied to a run with either `-var` or `-var-file` overwrite workspace-specific and variable set variables that have the same key. + +### 7. Local environment variables prefixed with `TF_VAR_` + +When using a CLI workflow, local environment variables prefixed with `TF_VAR_` (e.g., `TF_VAR_replicas`) overwrite workspace-specific, variable set, and `.auto.tfvars` file variables that have the same key. + +### 8. Workspace-specific variables + +Workspace-specific variables always overwrite variables from variable sets that have the same key. Refer to [overwrite variables from variable sets](/terraform/enterprise/workspaces/variables/managing-variables#overwrite-variable-sets) for details. + +### 9. Workspace-scoped variable owned by a project + +Variables in workspace-scoped variable sets are only applied to a subset of workspaces in a project. + +When workspace-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based on the lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same workspace, HCP Terraform will use any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +Variables sets scoped to workspaces that are owned by projects take precedence over sets with the same scope that are owned by organizations. + +### 10. Project-scoped variable set owned by a project + +Variables in project-scoped variable sets are only applied to the workspaces within the specified projects. + +When project-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based the on lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same project, HCP Terraform uses any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +Variables sets owned by projects take precedence over those owned by organizations. + +### 11. Workspace-scoped variable set owned by an organization + +Variables in workspace-scoped variable sets are only applied to the specified workspaces in an organization. + +When workspace-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based on the lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same workspace, HCP Terraform will use any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +### 12. Project-scoped variable set owned by an organization + +Variables in project-scoped variable sets are only applied to the workspaces within the specified projects. + +When project-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based the on lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same project, HCP Terraform uses any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +### 13. Global variable sets + +Workspace and project-scoped variable sets always take precedence over global variable sets that are applied to all workspaces within an organization. Terraform does not allow global variable sets to contain variables with the same key, so they cannot conflict. + +### 14. `*.auto.tfvars` variable files + +Variables in the HCP Terraform workspace and variables provided through the command line always overwrite variables with the same key from files ending in `.auto.tfvars`. + +### 15. `terraform.tfvars` variable file + +Variables in the `.auto.tfvars` files take precedence over variables in the `terraform.tfvars` file. + + + +Although HCP Terraform uses variables from `terraform.tfvars`, Terraform Enterprise currently ignores this file. + + + +## Precedence with priority variable sets + +You can select to prioritize all values of the variables in a variable set. +When a variable set is priority, the values take precedence over any variables with the same key set at a more specific scope. + +For example, variables in a priority global variable set would take precedence over all variables with the same key. + +If two priority variable sets with the same scope and ownership include the same variable key, HCP Terraform will determine precedence by the alphabetical order of the variable sets' names. + +While a priority variable set can enforce that Terraform variables use designated values, it does not guarantee that the configuration uses the variable. A user can still directly modify the Terraform configuration to remove usage of a variable and replace it with a hard-coded value. For stricter enforcement, we recommend using policy checks or run tasks. + +## Precedence example + +Consider an example workspace that has the following different kinds of variables and variable sets: + +| Source | Priority | Ownership | Scope | +| ------------------------------------------------------------- | -------- | ------------ | --------- | +| Priority **global** variable set | true | organization | global | +| Priority organization-owned **project-scoped** variable set | true | organization | project | +| Priority organization-owned **workspace-scoped** variable set | true | organization | workspace | +| Priority project-owned **project-scoped** variable set | true | project | project | +| Priority project-owned **workspace-scoped** variable set | true | project | workspace | +| Command line argument | N/A | N/A | run | +| Local environment variable | N/A | N/A | workspace | +| **Workspace-specific** variable | N/A | N/A | workspace | +| Project-owned **workspace-scoped** variable set | false | project | workspace | +| Project-owned **project-scoped** variable set | false | project | project | +| Organization-owned **workspace-scoped** variable set | false | organization | workspace | +| Organization-owned **project-scoped** variable set | false | organization | project | +| **Global** variable set | false | organization | global | + +If these variables and variable sets had the following variables applied: + +| Source (priority/ownership/scope) | Region | Var1 | Replicas | +| ------------------------------------------------------------- | ----------- | ---- | -------- | +| Priority **global** variable set | `us-east-1` | | | +| Priority organization-owned **project-scoped** variable set | `us-east-2` | | | +| Priority organization-owned **workspace-scoped** variable set | `us-west-1` | | | +| Priority project-owned **project-scoped** variable set | `eu-east-2` | | | +| Priority project-owned **workspace-scoped** variable set | `eu-west-1` | | | +| Command line argument | `us-west-2` | | `9` | +| Local environment variable | | | `8` | +| **Workspace-specific** variable | | `h` | `1` | +| Project-owned **workspace-scoped** variable set | | `y` | `2` | +| Project-owned **project-scoped** variable set | | | `4` | +| Organization-owned **workspace-scoped** variable set | | `z` | `3` | +| Organization-owned **project-scoped** variable set | | | `5` | +| **Global** variable set | | | `6` | + +When you trigger a run through the command line, these are the final values HCP Terraform assigns to each variable: + +| Variable | Value | +| -------- | ----------- | +| Region | `us-east-1` | +| Var1 | `h` | +| Replicas | `9` | diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/variables/managing-variables.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/variables/managing-variables.mdx new file mode 100644 index 0000000000..78dd91d594 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/enterprise/workspaces/variables/managing-variables.mdx @@ -0,0 +1,248 @@ +--- +page_title: Manage variables and variable sets in Terraform Enterprise +description: >- + Use workspace variables and variable sets to customize Terraform Enterprise + runs. +source: terraform-docs-common +--- + +# Manage variables and variable sets + +You can set variables specifically for each workspace or you can create variable sets to reuse the same variables across multiple workspaces. Refer to the [variables overview](/terraform/enterprise/workspaces/variables) documentation for more information about variable types, scope, and precedence. You can also set variable values specifically for each run on the command line. + +You can create and edit workspace-specific variables through: + +- The HCP Terraform UI, as detailed below. +- The Variables API for [workspace-specific variables](/terraform/enterprise/api-docs/workspace-variables) and [variable sets](/terraform/enterprise/api-docs/variable-sets). +- The `tfe` provider's [`tfe_variable`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/variable) resource, which can be more convenient for bulk management. + +## Permissions + +You must have [**Read variables** permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) to view the variables for a particular workspace and to view the variable sets in your organization. To create or edit workspace-specific variables within a workspace, you must have [**Read and write variables**](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) for that workspace. + +To create, update, or delete organization-owned variable sets, you must be one of the following: + +- A member of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) +- A member of a team with [**Manage all projects**](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects) +- A member of a team with [**Manage all workspaces**](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces) + +To create, edit, or apply project-owned variable sets, you must be part of a team with one of the following: + +- **Write** project permissions +- **Maintain** project permissions +- **Admin** project permissions +- [**Manage variable sets**](/terraform/enterprise/users-teams-organizations/permissions#general-project-permissions) project permissions +- [**Manage all projects**](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects) organization permissions + +## Run-Specific Variables + +Terraform 1.1 and later lets you set [Terraform variable](/terraform/enterprise/workspaces/variables#terraform-variables) values for a particular plan or apply on the command line. These variable values will overwrite workspace-specific and variable set variables with the same key. Refer to the [variable precedence](/terraform/enterprise/workspaces/variables#precedence) documentation for more details. + +You can set run-specific Terraform variable values by: + +- Specifying `-var` and `-var-file` arguments. For example: + + terraform apply -var="key=value" -var-file="testing.tfvars" +- Creating local environment variables prefixed with `TF_VAR_`. For example, if you declare a variable called `replicas` in your configuration, you could create a local environment variable called `TF_VAR_replicas` and set it to a particular value. When you use the [CLI Workflow](/terraform/enterprise/run/cli), Terraform automatically identifies these environment variables and applies their values to the run. + +Refer to the [variables on the command line](/terraform/language/values/variables#variables-on-the-command-line) documentation for more details and examples. + +## Workspace-Specific Variables + +To view and manage a workspace's variables, go to the workspace and click the **Variables** tab. + +The **Variables** page appears, showing all workspace-specific variables and variable sets applied to the workspace. This is where you can add, edit, and delete workspace-specific variables. You can also apply and remove variable sets from the workspace. + +The **Variables** page is not available for workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode). HCP Terraform does not evaluate workspace variables or variable sets in local execution mode. + +### Add a Variable + +To add a variable: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select the workspace you want to define a variable for. + +2. Go to the workspace **Variables** page and click **+ Add variable** in the **Workspace Variables** section. + +3. Choose a variable category (Terraform or environment), optionally mark the variable as [sensitive](#sensitive-values), and enter a variable key, value, and optional description. For Terraform variables only, you can check the **HCL** checkbox to enter a value in HashiCorp Configuration Language. + + Refer to [variable values and format](#variable-values-and-format) for variable limits, allowable values, and formatting. + +4. Click **Save variable**. The variable now appears in the list of the workspace's variables and HCP Terraform will apply it to runs. + +### Edit a Variable + +To edit a variable: + +1. Click the ellipses next to the variable you want to edit and select **Edit**. +2. Make any desired changes and click **Save variable**. + +### Delete a Variable + +To delete a variable: + +1. Click the ellipses next to the variable you want to delete and select **Delete**. +2. Click **Yes, delete variable** to confirm your action. + +## Loading Variables from Files + +You can set [Terraform variable](/terraform/enterprise/workspaces/variables#terraform-variables) values by providing any number of [files ending in `.auto.tfvars`](/terraform/language/values/variables#variable-files) to workspaces that use Terraform 0.10.0 or later. When you trigger a run, Terraform automatically loads and uses the variables defined in these files. If any variable from the workspace has the same key as a variable in the file, the workspace variable overwrites variable from the file. + +You can only do this with files ending in `auto.tfvars` or `terraform.tfvars`. You can apply other types of `.tfvars` files [using the command line](#run-specific-variables) for each run. + +~> **Note:** HCP Terraform loads variables from files ending in `auto.tfvars` for each Terraform run, but does not automatically persist those variables to the HCP Terraform workspace or display them in the **Variables** section of the workspace UI. + +## Variable Sets + +> **Hands On:** Try the [Manage Variable Sets in HCP Terraform tutorial](/terraform/tutorials/cloud/cloud-multiple-variable-sets) tutorial. + +Variable sets are reusable collections of variables that you can apply to multiple workspaces. You can create variable sets under an organization or a project. Whether the variable set is owned by an organization or a project determines the permissions required to manage that set. Learn more about [variable set permissions](#permissions). + +HCP Terraform does not evaluate variable sets during Terraform runs for workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode). + +Organizations or projects can own variable sets. To view variable sets, click **Settings** in your organization or project, then click **Variable sets**. + +The **Variable sets** page lists all of the organization's or project's variable sets. Click on a variable set to open it and review details about its variables and scoping. + +### Create Variable Sets + +To create a variable set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the **Settings** page for your organization or project. + +2. Click **Variable Sets**. + +3. Click **Create variable set**. + +4. Choose a descriptive **Name** for the variable set. You can use any combination of numbers, letters, and characters. + +5. Write an optional **Description** that tells other users about the purpose of the variable set and what it contains. + +6. Choose a variable set scope: + - Organization-owned + - **Apply globally:** HCP Terraform automatically applies this global variable set to all existing and future workspaces. + - **Apply to specific projects and workspaces:** Use the text fields to search for and select workspaces and projects to apply this variable set to. This affects all current and future workspaces for any selected projects. After creation, users can also [add this variable set to their workspaces](#apply-or-remove-variable-sets-from-inside-a-workspace). + - Project-owned + - **Apply to the entire project:** HCP Terraform automatically applies this variable set to all existing and future workspaces in the project. + - **Apply to specific workspaces in the project:** Use the text fields to search for and select workspaces to apply this variable set to. After creation, users can also [add this variable set to their workspaces](#apply-or-remove-variable-sets-from-inside-a-workspace). + +7. Add one or more variables: Click **+ Add variable**, choose a variable type (Terraform or environment), optionally mark the variable as [sensitive](#sensitive-values), and enter a variable name, value, and optional description. Then, click **Save variable**. + + Refer to [variable values and format](#variable-values-and-format) for variable limits, allowable values, and formatting. + + ~> **Note:** HCP Terraform will error if you try to declare variables with the same key in multiple global variable sets. + +8. Click **Create variable set.** HCP Terraform adds the new variable set to any specified workspaces and displays it on the **Variable Sets** page. + +### Edit Variable Sets + +To edit or remove a variable set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the **Settings** page for your organization or project. + +2. Click **Variable Sets**. + +3. Select the variable set you want to edit. That specific variable set page appears, where you can change the variable set settings. Refer to [create variable sets](#create-variable-sets) for details. + +### Delete Variable Sets + +Deleting a variable set can be a disruptive action, especially if the variables are required to execute runs. We recommend informing organization, project, and workspace owners before removing a variable set. + +To delete a variable set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the **Settings** page for your organization or project. + +2. Click **Variable Sets**. + +3. Select **Delete variable set**. Enter the variable set name and click **Delete variable set** to confirm this action. HCP Terraform deletes the variable set and removes it from all workspaces. Runs within those workspaces will no longer use the variables from the variable set. + +### Apply or Remove Variable Sets From Inside a Workspace + +To apply a variable set to a specific workspace: + +1. Navigate to the workspace and click the **Variables** tab. The **Variables** page appears, showing all workspace-specific variables and variable sets applied to the workspace. + +2. In the **Variable sets** section, click **Apply Variable Set**. Select the variable set you want to apply to your workspace, and click **Apply variable set**. The variable set appears in the workspace's variable sets list and HCP Terraform will now apply the variables to runs. + +To remove a variable set from within a workspace: + +1. Navigate to the workspace and click the **Variables** tab. The **Variables** page appears, showing all workspace-specific variables and variable sets applied to the workspace. +2. Click the ellipses button next to the variable set and select **Remove variable set**. +3. Click **Remove variable set** in the dialog box. HCP Terraform removes the variable set from this workspace, but it remains available to other workspaces in the organization. + +## Overwrite Variable Sets + +You can overwrite variables defined in variable sets within a workspace. For example, you may want to use a different set of provider credentials in a specific workspace. + +To overwrite a variable from a variable set, [create a new workspace-specific variable](#workspace-specific-variables) of the same type with the same key. HCP Terraform marks any variables that you overwrite with a yellow **OVERWRITTEN** flag. When you click the overwritten variable, HCP Terraform highlights the variable it will use during runs. + +Variables within a variable set can also automatically overwrite variables with the same key in other variable sets applied to the same workspace. Though variable sets are created for the organization or project, these overwrites occur within each workspace. Refer to [variable precedence](/terraform/enterprise/workspaces/variables#precedence) for more details. + +## Priority Variable Sets + +The values in priority variable sets overwrite any variables with the same key set at more specific scopes. This includes variables set using command line flags, or through`.*auto.tfvars` and `terraform.tfvars` files. + +It is still possible for a user to directly modify the Terraform configuration and remove usage of a variable and replace it with a hard coded value. For stricter enforcement, we recommend using policy checks or run tasks. +Refer to [variable precedence](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets) for more details. + +## Variable Values and Format + +The limits, allowable values, and required format are the same for both workspace-specific variables and variable sets. + +### Security + +HCP Terraform encrypts all variable values securely using [Vault's transit backend](/vault/docs/secrets/transit) prior to saving them. This ensures that no out-of-band party can read these values without proper authorization. However, HCP Terraform stores variable [descriptions](#variable-description) in plain text, so be careful with the information you save in a variable description. + +We also recommend passing credentials to Terraform as environment variables instead of Terraform variables when possible, since Terraform runs receive the full text of all Terraform variable values, including [sensitive](#sensitive-values) ones. It may print the values in logs and state files if the configuration sends the value to an output or a resource parameter. Sentinel mocks downloaded from runs will also contain the sensitive values of Terraform variables. + +Although HCP Terraform does not store environment variables in state, it can include them in log files if `TF_LOG` is set to `TRACE`. + +#### Dynamic Credentials + +An alternative to passing static credentials for some providers is to use [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials). + +Dynamic credentials allows for using temporary per-run credentials and eliminates the need to manually rotate secrets. + +### Character Limits + +The following limits apply to variables: + +| Component | Limit | +| ----------- | -------------- | +| description | 512 characters | +| key | 128 characters | +| value | 256 kilobytes | + +### Multi-Line Text + +You can type or paste multi-line text into variable value text fields. + +### HashiCorp Configuration Language (HCL) + +You can use HCL for Terraform variables, but not for environment variables. The same Terraform version that performs runs in the workspace will interpret the HCL. + +Variable values are strings by default. To enter list or map values, click the variable’s **HCL** checkbox (visible when editing) and enter the value with the same HCL syntax you would use when writing Terraform code. For example: + +```hcl +{ + us-east-1 = "image-1234" + us-west-2 = "image-4567" +} +``` + +### Sensitive Values + +!> **Warning:** There are some cases when even sensitive variables are included in logs and state files. Refer to [security](#security) for more information. + +Terraform often needs cloud provider credentials and other sensitive information that should not be widely available within your organization. To protect these secrets, you can mark any Terraform or environment variable as sensitive data by clicking its **Sensitive** checkbox that is visible during editing. + +Marking a variable as sensitive makes it write-only and prevents all users (including you) from viewing its value in the HCP Terraform UI or reading it through the Variables API endpoint. + +Users with permission to read and write variables can set new values for sensitive variables, but other attributes of a sensitive variable cannot be modified. To update other attributes, delete the variable and create a new variable to replace it. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Variable Description + +!> **Warning:** Variable descriptions are not encrypted, so do not include any sensitive information. + +Variable descriptions are optional, and help distinguish between similarly named variables. They are only shown on the **Variables** page and are completely independent from any variable descriptions declared in Terraform CLI. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/README.md b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/README.md new file mode 100644 index 0000000000..5835c582d5 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/README.md @@ -0,0 +1,10 @@ + +# Partials + +Partials allow you to share content across as many different docs pages as you'd like. To see an example of a partial, check out the `replicated-and-fdo` folder. You can write some in MDX, then import into a docs page like so: + +```mdx +@include "replicated-and-fdo/architecture/data-security-partial.mdx" +``` + +With that in place you can made updates directly to a partial and it updates the content everywhere the site uses that partial! Meaning, we don't have to duplicate and maintain information across pages! diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspace-with-vcs.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspace-with-vcs.mdx new file mode 100644 index 0000000000..80f04888bf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspace-with-vcs.mdx @@ -0,0 +1,196 @@ +```json +{ + "data": { + "id": "ws-KTuq99JSzgmDSvYj", + "type": "workspaces", + "attributes": { + "actions": { + "is-destroyable": true + }, + "allow-destroy-plan": true, + "apply-duration-average": null, + "assessments-enabled": false, + "auto-apply": false, + "auto-apply-run-trigger": false, + "auto-destroy-at": null, + "auto-destroy-activity-duration": null, + "created-at": "2021-08-16T21:50:58.726Z", + "description": null, + "environment": "default", + "execution-mode": "remote", + "file-triggers-enabled": true, + "global-remote-state": false, + "latest-change-at": "2021-08-16T21:50:58.726Z", + "locked": false, + "locked-reason": "", + "name": "workspace-2", + "oauth-client-name": "github example", + "operations": true, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-queue-run": true, + "can-read-run": true, + "can-read-variable": true, + "can-update-variable": true, + "can-read-state-versions": true, + "can-read-state-outputs": true, + "can-create-state-versions": true, + "can-queue-apply": true, + "can-lock": true, + "can-unlock": true, + "can-force-unlock": true, + "can-read-settings": true, + "can-manage-tags": true, + "can-manage-run-tasks": true, + "can-force-delete": true, + "can-manage-assessments": true, + "can-manage-ephemeral-workspaces": false, + "can-read-assessment-results": true, + "can-queue-destroy": true + }, + "apply-duration-average": 35000, + "plan-duration-average": 53000, + "policy-check-failures": null, + "queue-all-runs": false, + "resource-count": 10, + "run-failures": 3, + "source": "tfe-api", + "source-name": null, + "source-url": null, + "speculative-enabled": true, + "structured-run-output-enabled": true, + "tag-names": [], + "terraform-version": "1.9.4", + "trigger-prefixes": [], + "vcs-repo": { + "branch": "", + "display-identifier": "example/terraform-test-proj", + "identifier": "example/terraform-test-proj", + "ingress-submodules": false, + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "repository-http-url": "https://github.com/example/terraform-test-proj", + "service-provider": "github", + "tags-regex": null, + "webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87" + }, + "vcs-repo-identifier": "example/terraform-test-proj", + "working-directory": "", + "workspace-kpis-runs-count": null, + "setting-overwrites": { + "execution-mode": true, + "agent-pool": true + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/workspace-2", + "self-html": "/app/my-organization/workspaces/workspace-2" + }, + "relationships": { + "relationships": { + "agent-pool": { + "data": null + }, + "current-configuration-version": { + "data": null + }, + "current-run": { + "data": { + "id": "run-hjy7ndEkmCtn31ps", + "type": "runs" + }, + "links": { + "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps" + } + }, + "latest-run": { // Deprecated; same as current-run + "data": { + "id": "run-hjy7ndEkmCtn31ps", + "type": "runs" + }, + "links": { + "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps" + } + }, + "current-state-version": { + "data": { + "id": "sv-hjy7ndEkmCtn31ps", + "type": "state-versions" + }, + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version" + } + }, + "current-configuration-version": { + "data": { + "id": "cv-hjy7ndEkmCtn31ps", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps" + } + }, + "current-assessment-result": { + "data": null + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-hjy7ndEkmCtn31ps", + "type": "workspace-outputs" + } + ], + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs" + } + }, + "project": { + "data": { + "id": "prj-hjy7ndEkmCtn31ps", + "type": "projects" + } + }, + "readme": { + "data": null + }, + "remote-state-consumers": { + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers" + } + }, + "ssh-key": { + "data": { + "id": "sshkey-hjy7ndEkmCtn31ps", + "type": "ssh-keys" + }, + "links": { + "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps" + } + }, + "locked-by": { + "data": { + "id": "user-hjy7ndEkmCtn31ps", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-hjy7ndEkmCtn31ps" + } + }, + "vars": { + "data": [ + { + "id": "var-hjy7ndEkmCtn31ps", + "type": "vars" + } + ] + }, + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspace.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspace.mdx new file mode 100644 index 0000000000..ec7885457c --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspace.mdx @@ -0,0 +1,195 @@ +```json +{ + "data": { + "id": "ws-6jrRyVDv1J8zQMB5", + "type": "workspaces", + "attributes": { + "actions": { + "is-destroyable": true + }, + "allow-destroy-plan": true, + "assessments-enabled": false, + "auto-apply": false, + "auto-apply-run-trigger": false, + "auto-destroy-at": null, + "auto-destroy-status": null, + "auto-destroy-activity-duration": null, + "inherits-project-auto-destroy": null, + "created-at": "2021-08-16T21:22:49.566Z", + "description": null, + "environment": "default", + "execution-mode": "agent", + "file-triggers-enabled": true, + "global-remote-state": false, + "latest-change-at": "2021-08-16T21:22:49.566Z", + "last-assessment-result-at" : "2021-08-17T21:20:12.908Z", + "locked": true, + "locked-reason": null, + "name": "workspace-1", + "oauth-client-name": null, + "operations": true, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-queue-run": true, + "can-read-run": true, + "can-read-variable": true, + "can-update-variable": true, + "can-read-state-versions": true, + "can-read-state-outputs": true, + "can-create-state-versions": true, + "can-queue-apply": true, + "can-lock": true, + "can-unlock": true, + "can-force-unlock": true, + "can-read-settings": true, + "can-manage-tags": true, + "can-manage-run-tasks": true, + "can-force-delete": true, + "can-manage-assessments": true, + "can-manage-ephemeral-workspaces": false, + "can-read-assessment-results": true, + "can-queue-destroy": true + }, + "apply-duration-average": 35000, + "plan-duration-average": 53000, + "policy-check-failures": null, + "queue-all-runs": false, + "resource-count": 10, + "run-failures": 3, + "source": "tfe-api", + "source-name": null, + "source-url": null, + "speculative-enabled": true, + "structured-run-output-enabled": true, + "tag-names": [], + "terraform-version": "1.9.4", + "trigger-prefixes": [], + "updated-at": "2021-08-16T21:22:49.566Z", + "vcs-repo": null, + "vcs-repo-identifier": null, + "working-directory": null, + "workspace-kpis-runs-count": 8, + "setting-overwrites": { + "execution-mode": true, + "agent-pool": true + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/workspace-1", + "self-html": "/app/my-organization/workspaces/workspace-1" + }, + "relationships": { + "agent-pool": { + "data": { + "id": "apool-QxGd2tRjympfMvQc", + "type": "agent-pools" + } + }, + "current-configuration-version": { + "data": null + }, + "current-run": { + "data": { + "id": "run-hjy7ndEkmCtn31ps", + "type": "runs" + }, + "links": { + "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps" + } + }, + "latest-run": { // Deprecated; same as current-run + "data": { + "id": "run-hjy7ndEkmCtn31ps", + "type": "runs" + }, + "links": { + "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps" + } + }, + "current-state-version": { + "data": { + "id": "sv-hjy7ndEkmCtn31ps", + "type": "state-versions" + }, + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version" + } + }, + "current-configuration-version": { + "data": { + "id": "cv-hjy7ndEkmCtn31ps", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps" + } + }, + "current-assessment-result": { + "data": null + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-hjy7ndEkmCtn31ps", + "type": "workspace-outputs" + }, + { + "id": "wsout-hjy7ndEkmCtn31ps", + "type": "workspace-outputs" + } + ], + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs" + } + }, + "project": { + "data": { + "id": "prj-hjy7ndEkmCtn31ps", + "type": "projects" + } + }, + "readme": { + "data": null + }, + "remote-state-consumers": { + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers" + } + }, + "ssh-key": { + "data": { + "id": "sshkey-hjy7ndEkmCtn31ps", + "type": "ssh-keys" + }, + "links": { + "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps" + } + }, + "locked-by": { + "data": { + "id": "user-hjy7ndEkmCtn31ps", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-hjy7ndEkmCtn31ps" + } + }, + "vars": { + "data": [ + { + "id": "var-hjy7ndEkmCtn31ps", + "type": "vars" + } + ] + }, + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspaces-list.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspaces-list.mdx new file mode 100644 index 0000000000..0d73d52e7d --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/api-code-blocks/workspaces-list.mdx @@ -0,0 +1,214 @@ +```json +{ + "data": [ + { + "id": "ws-6jrRyVDv1J8zQMB5", + "type": "workspaces", + "attributes": { + "actions": { + "is-destroyable": true + }, + "allow-destroy-plan": true, + "assessments-enabled": false, + "auto-apply": false, + "auto-apply-run-trigger": false, + "auto-destroy-at": null, + "auto-destroy-status": null, + "auto-destroy-activity-duration": null, + "inherits-project-auto-destroy": null, + "created-at": "2021-08-16T21:22:49.566Z", + "description": null, + "environment": "default", + "execution-mode": "agent", + "file-triggers-enabled": true, + "global-remote-state": false, + "latest-change-at": "2021-08-16T21:22:49.566Z", + "last-assessment-result-at" : "2021-08-17T21:20:12.908Z", + "locked": true, + "locked-reason": null, + "name": "workspace-1", + "oauth-client-name": null, + "operations": true, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-queue-run": true, + "can-read-run": true, + "can-read-variable": true, + "can-update-variable": true, + "can-read-state-versions": true, + "can-read-state-outputs": true, + "can-create-state-versions": true, + "can-queue-apply": true, + "can-lock": true, + "can-unlock": true, + "can-force-unlock": true, + "can-read-settings": true, + "can-manage-tags": true, + "can-manage-run-tasks": true, + "can-force-delete": true, + "can-manage-assessments": true, + "can-manage-ephemeral-workspaces": false, + "can-read-assessment-results": true, + "can-queue-destroy": true + }, + "apply-duration-average": 35000, + "plan-duration-average": 53000, + "policy-check-failures": null, + "queue-all-runs": false, + "resource-count": 10, + "run-failures": 3, + "source": "tfe-api", + "source-name": null, + "source-url": null, + "speculative-enabled": true, + "structured-run-output-enabled": true, + "tag-names": [], + "terraform-version": "1.9.4", + "trigger-prefixes": [], + "updated-at": "2021-08-16T21:22:49.566Z", + "vcs-repo": null, + "vcs-repo-identifier": null, + "working-directory": null, + "workspace-kpis-runs-count": 8, + "setting-overwrites": { + "execution-mode": true, + "agent-pool": true + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/workspace-1", + "self-html": "/app/my-organization/workspaces/workspace-1" + }, + "relationships": { + "agent-pool": { + "data": { + "id": "apool-QxGd2tRjympfMvQc", + "type": "agent-pools" + } + }, + "current-configuration-version": { + "data": null + }, + "current-run": { + "data": { + "id": "run-hjy7ndEkmCtn31ps", + "type": "runs" + }, + "links": { + "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps" + } + }, + "latest-run": { // Deprecated; same as current-run + "data": { + "id": "run-hjy7ndEkmCtn31ps", + "type": "runs" + }, + "links": { + "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps" + } + }, + "current-state-version": { + "data": { + "id": "sv-hjy7ndEkmCtn31ps", + "type": "state-versions" + }, + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version" + } + }, + "current-configuration-version": { + "data": { + "id": "cv-hjy7ndEkmCtn31ps", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps" + } + }, + "current-assessment-result": { + "data": null + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-hjy7ndEkmCtn31ps", + "type": "workspace-outputs" + }, + { + "id": "wsout-hjy7ndEkmCtn31ps", + "type": "workspace-outputs" + } + ], + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs" + } + }, + "project": { + "data": { + "id": "prj-hjy7ndEkmCtn31ps", + "type": "projects" + } + }, + "readme": { + "data": null + }, + "remote-state-consumers": { + "links": { + "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers" + } + }, + "ssh-key": { + "data": { + "id": "sshkey-hjy7ndEkmCtn31ps", + "type": "ssh-keys" + }, + "links": { + "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps" + } + }, + "locked-by": { + "data": { + "id": "user-hjy7ndEkmCtn31ps", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-hjy7ndEkmCtn31ps" + } + }, + "vars": { + "data": [ + { + "id": "var-hjy7ndEkmCtn31ps", + "type": "vars" + } + ] + }, + } + }, + ], + "links": { + "first": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "last": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "next": null, + "prev": null, + "self": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "next-page": null, + "page-size": 20, + "prev-page": null, + "total-count": 1, + "total-pages": 1 + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/common-kubernetes-blocks/externalizing-secret-values.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/common-kubernetes-blocks/externalizing-secret-values.mdx new file mode 100644 index 0000000000..9c1a24ac85 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/common-kubernetes-blocks/externalizing-secret-values.mdx @@ -0,0 +1,17 @@ +### Externalizing secret values + +The Terraform Enterprise deployment configuration requires several secret values, such as keys, passwords, and certificates. You can populate these as part of the Helm `overrides.yaml` created before installation. However, this requires manual handling of secret values and may leave them exposed on the deployment host without further intervention. + +To mitigate this security concern, HashiCorp recommends populating these secret values into a Kubernetes Secret from a centralized secrets management platform using a trusted orchestrator like the [Vault Secrets Operator](https://developer.hashicorp.com/vault/docs/platform/k8s/vso) before installing Terraform Enterprise. + +You can then reference the Kubernetes Secret in the Terraform Enterprise Helm Chart: + +```yaml +env: + secretRefs: + - name: terraform-enterprise-managed-secrets +``` + +Terraform Enterprise also supports the [Vault CSI provider](https://developer.hashicorp.com/vault/docs/platform/k8s/csi). +This allows TFE pods to consume Vault secrets using CSI Secrets Store volumes. +More information can be found in the [Helm Chart documentation](https://github.com/hashicorp/terraform-enterprise-helm/blob/main/docs/configuration.md#vault-csi-provider). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/active-active-scaling-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/active-active-scaling-partial.mdx new file mode 100644 index 0000000000..59493e52fa --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/active-active-scaling-partial.mdx @@ -0,0 +1,44 @@ +## Scaling Beyond Two Nodes + +Terraform Enterprise supports scaling up to five nodes as part of the Active/Active deployment. When scaling beyond two nodes, you should also carefully evaluate and scale external services, particularly the database server. Regardless of the number of nodes, you must drain and scale down to a single node before upgrading. + +### PostgreSQL Server + +The Terraform Enterprise PostgreSQL server will typically hit the CPU capacity before other resources, so we recommend closely monitoring the CPU in a two-node configuration before scaling up to three or more nodes. You may also need to manually modify the database maximum connection count to allow for the additional load. Defaults vary, so please refer to the documentation for the cloud hosting your installation. + +- [AWS - RDS connection limits](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Limits.html#RDS_Limits.MaxConnections) +- [AWS - Aurora Scaling](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Managing.Performance.html) +- [Azure - Azure Database Limits](https://docs.microsoft.com/en-us/azure/postgresql/concepts-limits) +- [Google Cloud - Cloud SQL Quotes and Limits](https://cloud.google.com/sql/docs/quotas) +- [PostgreSQL 12 - Connection Documentation](https://www.postgresql.org/docs/12/runtime-config-connection.html) + +### Redis Server + +Some workloads may rarely cause spikes in the Redis server CPU or memory. We recommend monitoring the Redis server and scaling it up as necessary. + +- [AWS - Monitoring ElastiCache for Redis with CloudWatch](https://aws.amazon.com/blogs/database/monitoring-best-practices-with-amazon-elasticache-for-redis-using-amazon-cloudwatch/) +- [Azure - Monitor Azure Cache for Redis](https://docs.microsoft.com/en-us/azure/azure-cache-for-redis/cache-how-to-monitor) +- [Google Cloud - Monitoring Redis Instances](https://cloud.google.com/memorystore/docs/redis/monitoring-instances) + +### Network Infrastructure/API Limits + +As you scale Terraform Enterprise beyond two nodes, you may be adding additional stress to your network and dramatically increasing the number of API calls made in your cloud account. Each cloud has its own default limits and processes by which those limits might be increased. Please refer to the documentation for the cloud hosting your installation. + +- [AWS - EC2 instance network limits](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html) +- [AWS - Request Throttling for the EC2 API](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/throttling.html) +- [Azure - Virtual Machine Network Limits](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-machine-network-throughput) +- [Azure - Resource Manager Throttling](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/request-limits-and-throttling) +- [Google Cloud - Network Quotas and Limits](https://cloud.google.com/vpc/docs/quota) +- [Google Cloud - API rate limits](https://cloud.google.com/compute/docs/api-rate-limits) + +Depending on your infrastructure and Terraform Enterprise configuration, you may need to configure your application gateway or load balancer for sticky sessions. Sticky session refers to the practice of using a load balancer or gateway device with a specific setting enabled that ensures traffic is routed back to the original system that initiated a request. For example, an Active/Active deployment on Azure with SAML authentication requires sticky sessions to ensure the authentication with the SAML server is successful. The terminology for this varies across clouds. Refer to the documentation for your infrastructure. + +- [AWS - Sticky Sessions for your Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/sticky-sessions.html) +- [AWS - Configure sticky sessions for your Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-sticky-sessions.html) +- [Azure - Application Gateway Cookie-based affinity](https://docs.microsoft.com/en-us/azure/application-gateway/configuration-http-settings#cookie-based-affinity) +- [Azure - Load Balancer distribution modes: Session Persistence](https://docs.microsoft.com/en-us/azure/load-balancer/distribution-mode-concepts#session-persistence) +- [Google Cloud - Session affinity](https://cloud.google.com/load-balancing/docs/https#session_affinity) + +### HCP Terraform agents - Alternative Solution + +Instead of scaling Terraform Enterprise beyond two to five nodes, you can use [HCP Terraform agents](/terraform/enterprise/admin/agents-on-tfe). HCP Terraform agents can run in other regions, other clouds, and even private clouds. Agents poll Terraform Enterprise for work and then Terraform plans and applies will run on the target system that has the agent executable installed. This has a much smaller impact on the Terraform Enterprise servers than running Terraform locally. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/license-example-usage-payload.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/license-example-usage-payload.mdx new file mode 100644 index 0000000000..908d1967b6 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/license-example-usage-payload.mdx @@ -0,0 +1,167 @@ +### Product data collection reference + +The following JSON payload describes the product usage data that Terraform Enterprise collects. + +```json +{ + "version":"2", + "mode": "automatic", + "timestamp":"${TIME_OF_EXPORT}", + "signature": "${UUID}", + "checksum": "${UUID}", + "snapshots":[ + { + "snapshot_version":2, + "id":"${SNAPSHOT_ID}", + "timestamp":"${TIME_OF_EXPORT}", + "schema_version":"2.0.1", + "product":"terraform", + "process_id":"${PROCESS_ID}", + "product_version":"${TFE_VERSION}", + "license_id":"${LICENSE_IDENTIFIER}", + "checksum": "${SHA}", + "metrics":{ + "billable_rum_count":{ + "key": "billable_rum_count", + "value": 1, + "mode": "write" + }, + "billable_rum_count_workspace_80th_percentile":{ + "key": "billable_rum_count_workspace_80th_percentile", + "value": 1, + "mode": "write" + }, + "billable_rum_count_workspace_avg":{ + "key": "billable_rum_count_workspace_avg", + "value": 1, + "mode": "write" + }, + "billable_rum_count_workspace_max":{ + "key": "billable_rum_count_workspace_max", + "value": 1, + "mode": "write" + }, + "billable_rum_count_workspace_median":{ + "key": "billable_rum_count_workspace_median", + "value": 1, + "mode": "write" + }, + "billable_rum_count_workspace_min":{ + "key": "billable_rum_count_workspace_min", + "value": 1, + "mode": "write" + }, + "billable_rum_opt_in":{ + "key": "billable_rum_opt_in", + "value": 1, + "mode": "write" + }, + "ado_vcs_present":{ + "key": "ado_vcs_present", + "value": 1, + "mode": "write" + }, + "aws_provider_present":{ + "key": "aws_provider_present", + "value": 1, + "mode": "write" + }, + "azure_provider_present":{ + "key": "azure_provider_present", + "value": 1, + "mode": "write" + }, + "bitbucket_vcs_present":{ + "key": "bitbucket_vcs_present", + "value": 1, + "mode": "write" + }, + "continuous_validation_used_last_90_days":{ + "key": "continuous_validation_used_last_90_days", + "value": 1, + "mode": "write" + }, + "drift_detection_used_last_90_days":{ + "key": "drift_detection_used_last_90_days", + "value": 1, + "mode": "write" + }, + "gcp_provider_present":{ + "key": "gcp_provider_present", + "value": 1, + "mode": "write" + }, + "github_vcs_present":{ + "key": "github_vcs_present", + "value": 1, + "mode": "write" + }, + "gitlab_vcs_present":{ + "key": "gitlab_vcs_present", + "value": 1, + "mode": "write" + }, + "product_usage_reporting_opt_in":{ + "key": "product_usage_reporting_opt_in", + "value": 1, + "mode": "write" + }, + "run_tasks_used_last_90_days":{ + "key": "run_tasks_used_last_90_days", + "value": 1, + "mode": "write" + }, + "run_triggers_used_last_90_days":{ + "key": "run_triggers_used_last_90_days", + "value": 1, + "mode": "write" + }, + "sentinel_used_last_90_days":{ + "key": "sentinel_used_last_90_days", + "value": 1, + "mode": "write" + }, + "servicenow_catalog_billable_rum_count":{ + "key": "servicenow_catalog_billable_rum_count", + "value": 1, + "mode": "write" + }, + "servicenow_catalog_run_count":{ + "key": "servicenow_catalog_run_count", + "value": 1, + "mode": "write" + }, + "servicenow_catalog_workspace_count":{ + "key": "servicenow_catalog_workspace_count", + "value": 1, + "mode": "write" + }, + "teams_count":{ + "key": "teams_count", + "value": 1, + "mode": "write" + }, + "varsets_count":{ + "key": "varsets_count", + "value": 1, + "mode": "write" + }, + "workspacecount":{ + "key": "workspacecount", + "value": 1, + "mode": "write" + }, + "private_modules_count":{ + "key":"private_modules_count", + "value": 1, + "mode":"write" + }, + } + } + ], + "metadata":{ + + } + } +} +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/license-utilization-intro.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/license-utilization-intro.mdx new file mode 100644 index 0000000000..68bc1731bf --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/admin/license-utilization-intro.mdx @@ -0,0 +1,33 @@ +# License and product usage reporting + +This topic describes how to enable Terraform Enterprise to report license and product usage information to HashiCorp. This topic also outlines how HashiCorp uses license and product data it collects when automated data reporting is enabled. It is enabled by default, but automated license and product utilization data reporting can be disabled separately. + +## Data reporting privacy + +The process is GDPR compliant and consists of mostly computed metrics that never contain personal identifiable information (PII) or other sensitive information. Automated reporting shares the data with HashiCorp using a secure, unidirectional HTTPS API and makes an auditable record in the product logs each time it submits a report. + +## Enable automated license utilization reporting + +When automated license usage reporting is enabled, Terraform sends HashiCorp the minimum data required to validate license usage as defined in our contracts. As a result, you do not have to manually collect and report the usage data. + +License usage reports provide the following benefits: + +- Insight into how much more you can deploy under your current contract. +- Protection against over-utilization. +- Predictable consumption for budgeting purposes. + +Additionally, you can review license usage with your existing monitoring solutions, such as Splunk and Datadog. Monitoring license consumption enables you to optimize and manage your deployments. For instructions on how to forward your license usage data to a monitoring solution, refer to the following topics for instructions on forwarding logs: +- [Enable log forwarding on Replicated installations](/terraform/enterprise/deploy/replicated/monitoring/logging) +- [Enable log forwarding on non-Replicated installations](/terraform/enterprise/deploy/manage/monitor#external-log-forwarding). + + +To enable automated reporting, you need to make sure that outbound network traffic is configured correctly and upgrade your enterprise product to a version that supports it. If your installation is air-gapped or network settings are not in place, automated reporting will not work. + +### Allow outbound HTTPS traffic on port 443 + +Make sure that your network allows HTTPS egress on port 443 from `https://reporting.hashicorp.services` by allow-listing the following IP addresses: + +- `100.20.70.12` +- `35.166.5.22` +- `23.95.85.111` +- `44.215.244.1` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/architecture/data-security-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/architecture/data-security-partial.mdx new file mode 100644 index 0000000000..3e54c6d452 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/architecture/data-security-partial.mdx @@ -0,0 +1,49 @@ +# Data Security + +HCP Terraform takes the security of the data it manages +seriously. This table lists which parts of the HCP Terraform and Terraform Enterprise app can contain sensitive data, what storage is used, and what encryption is used. + +### HCP Terraform and Enterprise + +| Object | Storage | Encrypted | +| :----------------------------------- | :----------- | :----------------------- | +| Ingressed VCS Data | Blob Storage | Vault Transit Encryption | +| Terraform Plan Result | Blob Storage | Vault Transit Encryption | +| Terraform State | Blob Storage | Vault Transit Encryption | +| Terraform Logs | Blob Storage | Vault Transit Encryption | +| Terraform/Environment Variables | PostgreSQL | Vault Transit Encryption | +| Organization/Workspace/Team Settings | PostgreSQL | No | +| Account Password | PostgreSQL | bcrypt | +| 2FA Recovery Codes | PostgreSQL | Vault Transit Encryption | +| SSH Keys | PostgreSQL | Vault Transit Encryption | +| User/Team/Organization Tokens | PostgreSQL | HMAC SHA512 | +| OAuth Client ID + Secret | PostgreSQL | Vault Transit Encryption | +| OAuth User Tokens | PostgreSQL | Vault Transit Encryption | + +### Terraform Enterprise Specific + +| Object | Storage | Encrypted | +| :--------------------------- | :--------- | :----------------------- | +| Twilio Account Configuration | PostgreSQL | Vault Transit Encryption | +| SMTP Configuration | PostgreSQL | Vault Transit Encryption | +| SAML Configuration | PostgreSQL | Vault Transit Encryption | +| Vault Unseal Key | PostgreSQL | ChaCha20+Poly1305 | + +## Vault Transit Encryption + +The [Vault Transit Secret Engine](/vault/docs/secrets/transit) +handles encryption for data in-transit and is used when encrypting data from the +application to persistent storage. + +## Blob Storage Encryption + +All objects persisted to blob storage are symmetrically encrypted prior to being +written. Each object is encrypted with a unique encryption key. Objects are +encrypted using 128 bit AES in CTR mode. The key material is processed +through the [Vault transit secret engine](/vault/docs/secrets/transit), +which uses the default transit encryption cipher (AES-GCM with a 256-bit AES key +and a 96-bit nonce), and stored alongside the object. This pattern is called envelope encryption. + +The Vault transit secret engine's +[datakey generation](/vault/api-docs/secret/transit#generate-data-key) creates the encryption key material using bit material from the kernel's cryptographically secure pseudo-random +number generator (CSPRNG) as the `context` value. Blob storage encryption generates a unique key for each object and relies on envelope encryption, so Vault does not rotate the encryption key material for individual objects. The root encryption keys within the envelope encryption scheme are rotated automatically by HCP Terraform every 365 days. These keys are not automatically rotated within TFE. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/architecture/security-model-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/architecture/security-model-partial.mdx new file mode 100644 index 0000000000..d6f8d426df --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/architecture/security-model-partial.mdx @@ -0,0 +1,86 @@ +## Personas + +In addition to those listed in [HCP Terraform Security model](/terraform/cloud-docs/architectural-details/security-model), Terraform Enterprise requires the following personas for managing and administering the application. + +### Infrastructure Admin + +Outside of the application, administrators of the Terraform Enterprise deployment are responsible for managing the underlying infrastructure, upgrading the application, and configuring Terraform Enterprise either via the [Replicated admin console](/terraform/enterprise/deploy/replicated/install/interactive/config#system-configuration) or by editing the [application settings file](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer). + +Terraform Enterprise grants extensive permissions to this role, so we recommend limiting the number of users who are infrastructure admins in your organization. + +### Site Admin + +[Site admins](/terraform/enterprise/application-administration/admin-access) are responsible for application-level configuration of Terraform Enterprise. They can manage all users, workspaces, and organizations through the admin interface and have access to all data stored within Terraform Enterprise. Site admins are also responsible for configuring SAML and are the only users that can access Terraform Enterprise with a username and password once SAML is configured. + +Terraform Enterprise grants extensive permissions to this role, so we recommend limiting the number of users who are site admins in your organization. + +## Differences Between Terraform Enterprise and HCP Terraform Security Models + +All of the content on [HCP Terraform security model](/terraform/cloud-docs/architectural-details/security-model) applies to Terraform Enterprise, with the exception of the points listed below. + +### Terraform Enterprise Requires You to Manage and Secure the Underlying Network and Infrastructure + +Infrastructure admins are required to manage all aspects of the underlying infrastructure. This includes initial provisioning, secure configuration, access control, network ACL configuration, and OS-level software updates. Terraform Enterprise cannot ensure the security of your data if the underlying infrastructure is compromised. + +### You are Responsible for Updating Your Terraform Enterprise Deployment + +We release security fixes, application features, and bug fixes for Terraform Enterprise each month. Infrastructure admins are responsible for applying updates. + +### You are Responsible for Availability, Backups, and Disaster Recovery + +Infrastructure admins are responsible for all aspects of reliability and availability. Refer to Terraform Enterprise documentation on [monitoring](/terraform/enterprise/deploy/replicated/monitoring/monitoring), [backups and restores](/terraform/enterprise/deploy/replicated/administration/infrastructure/backup-restore), and [high availability mode (active/active)](/terraform/enterprise/deploy/replicated/administration/infrastructure/admin-cli) for more guidance on this topic. + +### Terraform Enterprise Isolates Terraform Operations via Docker Containers + +Unlike HCP Terraform, Terraform Enterprise performs all Terraform operations in Docker containers on the Terraform Enterprise host. The containers are assigned to an isolated Docker network to prevent them from communicating with Terraform Enterprise backend services. However, Terraform Enterprise does not perform any egress filtering, so Terraform runs can still access available network resources. + +### Terraform Enterprise Relies on Third Party Software for Licensing, Delivery, Installation, and Management + +Terraform Enterprise is built on top of a software platform developed by [Replicated](https://www.replicated.com/). The components necessary for installing Terraform Enterprise are hosted by Replicated, and software developed by Replicated is used for bootstrapping, configuring, and managing every Terraform Enterprise deployment. For more information, see [Security at Replicated](https://www.replicated.com/security/). + +## Recommendations for Securely Operating Terraform Enterprise + +In addition those provided in the [HCP Terraform security model](/terraform/cloud-docs/architectural-details/security-model), we recommend the following for Terraform Enterprise users. + +### Run Terraform Enterprise in an Isolated Network, Limit Ingress Ports, and Restrict Access to Underlying Infrastructure + +To minimize attack surface, we recommend running Terraform Enterprise in an isolated network and limiting ingress ports to only 80 and 443, as documented in [Network Requirements for Terraform Enterprise](/terraform/enterprise/deploy/replicated/requirements/network). + +Additionally, we recommend restricting access to the nodes that are running Terraform Enterprise. Terraform Enterprise can not ensure the security or integrity of your data if the underlying infrastructure is compromised. + +### Enable Optional Security Features + +Once you are ready to use Terraform Enterprise for production workloads, we recommend enabling these optional security features. + +#### Secure secondary hostnames + +You can configure Terraform Enterprise to allow incoming connections at more than one hostname. Refer to [Configure network access](/terraform/enterprise/deploy/configuration/network) for instructions. + +When configuring multiple hostnames, create and distribute TLS certificates for the secondary hostname in addition to the primary hostname. Refer to [TLS settings](/terraform/enterprise/deploy/reference/configuration#tls-settings) in the deployment configuration reference for additional information. + +#### Enable Strict Transport Security Header + +You can configure Terraform Enterprise to set the [Strict Transport Security (HSTS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) header by: + +- Visiting the installer dashboard "Settings" page and enabling “Force TLS” under the “SSL/TLS Configuration” section. +- Setting [force_tls](/terraform/enterprise/deploy/replicated/install/automated/automating-the-installer#force_tls) in the application settings file. + +~> **Note:** Once properly configured, the HSTS header cannot be disabled and will prevent clients from accessing your Terraform Enterprise domain via HTTP or HTTPS using a self-signed cert. We recommend only enabling this setting for production Terraform Enterprise deployments. + +#### Disable Global Remote State Sharing + +Terraform Enterprise allows site admins to enable [global remote state sharing](/terraform/enterprise/application-administration/general#remote-state-sharing), which allows any workspace to access the state versions of any other workspace within the same organization. We recommend disabling this feature and relying on [controlled remote state access](https://www.hashicorp.com/blog/announcing-controlled-remote-state-access-for-terraform-cloud-and-enterprise) if you need to share state between workspaces. + +#### Treat Support Bundles with Care + +Terraform Enterprise uses support bundles to share diagnostic information with HashiCorp support. Please note that support bundles may contain sensitive information from your Terraform Enterprise installation. You should not share them with untrusted parties and should delete them as soon as possible. + +#### Update Terraform Enterprise Often + +We release Terraform Enterprise updates each month. Updates may contain additional security features or fixes for existing security vulnerabilities, so we recommend establishing a process for periodically updating your Terraform Enterprise installation. + +#### Subscribe to Terraform Enterprise Security Bulletins + +We publish updates that address security vulnerabilities in HashiCorp products. You can find them in the Security category of [HashiCorp Discuss](https://discuss.hashicorp.com/c/security/). + +We recommend that Terraform Enterprise infrastructure admins follow the [documented steps](https://discuss.hashicorp.com/t/about-hashicorp-security-updates/15330) to subscribe to email notifications or the RSS feed for Terraform Enterprise security updates. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/monitoring/logging/supported-destinations-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/monitoring/logging/supported-destinations-partial.mdx new file mode 100644 index 0000000000..c1279b192b --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/monitoring/logging/supported-destinations-partial.mdx @@ -0,0 +1,178 @@ +### Amazon CloudWatch + +Sending to Amazon CloudWatch is only supported when Terraform Enterprise is +located within AWS due to how Fluent Bit reads AWS credentials. + +This example configuration forwards all logs to Amazon CloudWatch. Refer to the +[`cloudwatch_logs` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/cloudwatch) +for more information. + +```ini +[OUTPUT] + Name cloudwatch_logs + Match * + region us-east-1 + log_group_name example-log-group + log_stream_name example-log-stream + auto_create_group On +``` + +-> **Note:** In Terraform Enterprise installations using AWS external services, +Fluent Bit will have access to the same `AWS_ACCESS_KEY_ID` and +`AWS_SECRET_ACCESS_KEY` environment variables that are used for object storage. + +### Amazon S3 + +Sending to Amazon S3 is only supported when Terraform Enterprise is located +within AWS due to how Fluent Bit reads AWS credentials. + +This example configuration forwards all logs to Amazon S3. Refer to the +[`s3` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/s3) +for more information. + +```ini +[OUTPUT] + Name s3 + Match * + bucket example-bucket + region us-east-1 + total_file_size 250M + s3_key_format /$TAG/%Y/%m/%d/%H/%M/%S/$UUID.gz + s3_key_format_tag_delimiters .- +``` + +-> **Note:** In Terraform Enterprise installations using AWS external services, +Fluent Bit will have access to the same `AWS_ACCESS_KEY_ID` and +`AWS_SECRET_ACCESS_KEY` environment variables that are used for object storage. + +### Azure Blob Storage + +This example configuration forwards all logs to Azure Blob Storage. Refer to the +[`azure_blob` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/azure_blob) +for more information. + +```ini +[OUTPUT] + name azure_blob + match * + account_name example-account-name + shared_key example-access-key + path logs + container_name example-container-name + auto_create_container on + tls on +``` + +### Azure Log Analytics + +This example configuration forwards all logs to Azure Log Analytics. Refer to +the [`azure` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/azure) +for more information. + +```ini +[OUTPUT] + name azure + match * + Customer_ID example-log-analytics-workspace-id + Shared_Key example-access-key +``` + +### Datadog + +This example configuration forwards all logs to Datadog. Refer to the +[`datadog` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/datadog) +for more information. + +```ini +[OUTPUT] + Name datadog + Match * + Host http-intake.logs.datadoghq.com + TLS on + compress gzip + apikey example-api-key + dd_service terraform_enterprise + dd_source docker + dd_tags environment:development,owner:engineering +``` + +### Forward + +This example configuration forwards all logs to a listening Fluent Bit or +Fluentd instance. Refer to the +[`forward` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/forward) +for more information. + +```ini +[OUTPUT] + Name forward + Match * + Host fluent.example.com + Port 24224 +``` + +### Google Cloud Platform Cloud Logging + +Sending to Google Cloud Platform Cloud Logging is only supported when Terraform +Enterprise is located within GCP due to how Fluent Bit reads GCP credentials. + +This example configuration forwards all logs to Google Cloud Platform Cloud +Logging (formerly known as Stackdriver). Refer to the +[`stackdriver` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/stackdriver) +for more information. + +```ini +[OUTPUT] + Name stackdriver + Match * + location us-east1 + namespace terraform_enterprise + node_id example-hostname + resource generic_node +``` + +-> **Note:** In Terraform Enterprise installations using GCP external services, +Fluent Bit will have access to the `GOOGLE_SERVICE_CREDENTIALS` environment +variable that points to a file containing the same GCP Service Account JSON +credentials that are used for object storage. + +### Splunk Enterprise HTTP Event Collector (HEC) + +This example configuration forwards all logs to Splunk Enterprise via the HTTP +Event Collector (HEC) interface. Refer to the +[`splunk` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/splunk) +for more information. + +```ini +[OUTPUT] + Name splunk + Match * + Host example-splunk-hec-endpoint + Port 8088 + Splunk_Token example-splunk-token +``` + +### Syslog + +This example configuration forwards all logs to a Syslog-compatible endpoint. +Refer to the +[`syslog` Fluent Bit output plugin documentation](https://docs.fluentbit.io/manual/pipeline/outputs/syslog) +for more information. + +```ini +[OUTPUT] + Name syslog + Match * + host example-syslog-host + port 514 + mode tcp + syslog_message_key log + syslog_severity_key PRIORITY + syslog_hostname_key _HOSTNAME + syslog_appname_key SYSLOG_IDENTIFIER + syslog_procid_key _PID +``` + + +The `syslog_message_key` should not be changed from `log`. If that value is changed, the application will no longer forward logs. + \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/custom-image.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/custom-image.mdx new file mode 100644 index 0000000000..49718a8a90 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/custom-image.mdx @@ -0,0 +1,36 @@ +Terraform Enterprise performs Terraform runs in ephemeral containers, using a +built-in [tfc-agent](https://hub.docker.com/r/hashicorp/tfc-agent) container image by default. To add custom tools or logic to your +Terraform run environment, you must build a custom image and configure +Terraform Enterprise to use it. + +### Agent + +Build your custom image using the `Dockerfile` below. Then update the +`custom_agent_image_tag` setting with your image (e.g. +`registry.example.com/example/tfc-agent:custom-tag`). + +![The `custom_agent_image_tag` setting in the user interface.](/img/docs/tfe_console-custom_agent_image_tag.png) + +#### Requirements + +- The base image must be `hashicorp/tfc-agent:1.6.0` or later. + +#### Dockerfile + +```Dockerfile +FROM hashicorp/tfc-agent:latest + +# Switch the to root user in order to perform privileged actions such as +# installing software. +USER root + +# Install sudo. The container runs as a non-root user, but people may rely on +# the ability to apt-get install things. +RUN apt-get -y install sudo + +# Permit tfc-agent to use sudo apt-get commands. +RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoers.d/50-tfc-agent + +# Switch back to the tfc-agent user as needed by Terraform agents. +USER tfc-agent +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/minio-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/minio-partial.mdx new file mode 100644 index 0000000000..2875fd4c26 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/minio-partial.mdx @@ -0,0 +1,93 @@ +# Minio Setup Guide for Terraform Enterprise + +This document provides an overview for setting up [Minio](https://minio.io) for external object storage for HashiCorp Terraform Enterprise. + +## Required Reading + +- Ensure you are familiar with Terraform Enterprise's operation and [installation requirements](/terraform/enterprise/deploy/replicated/install/pre-install-checklist), and especially the [Operational Mode Decision](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#operational-mode-decision). +- Familiarize yourself with [Minio](https://minio.io). + +## Overview + +When configured to use _External Services_, Terraform Enterprise must be connected to a storage service to persist workspace state and other file-based data. Native support exists for Azure Blob Storage, Amazon S3, and services that are API-compatible with Amazon S3. If you are not using Azure or a cloud provider with an S3-compatible service, or you are running Terraform Enterprise in an environment without a storage service, it may be possible to use [Minio](https://minio.io) instead. + +## Installation + +~> **Note:** This is not a production-ready configuration: it's intended to guide you to a working configuration that can later be automated and hardened. + +This guide will walk through installing Minio in a Docker container alongside Terraform Enterprise on the same host, with Terraform Enterprise configured in the _External Services_ [operational mode](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#choose-an-operational-mode). Data will not be persisted outside of an ephemeral Docker volume, Minio will not start on system boot, etc. The guide assumes your instance will have access to the Internet and that you will be performing an online install of Terraform Enterprise. + +### System preparation + +Ensure your Linux instance meets the [requirements](/terraform/enterprise/deploy/replicated/install/pre-install-checklist#configure-linux-instance). You will need [jq](https://stedolan.github.io/jq/) (a command-line JSON processor), and the [AWS CLI](https://aws.amazon.com/cli/). + +You also need a PostgreSQL database that meets the [requirements](/terraform/enterprise/deploy/replicated/requirements/data-storage/postgres-requirements), as this is part of the _External Services_ operational mode. + +### Terraform Enterprise installation + +Begin with an [online installation](/terraform/enterprise/deploy/replicated/install/interactive/installer#run-the-installer-online). Once the installation script has finished and you're presented with the following text, move on to the next section: + +``` +To continue the installation, visit the following URL in your browser: + + https://:8800 +``` + +### Start Minio + +Now you'll start the Minio container, mounting a volume so that you can gain access to the generated config: + +``` +docker run \ + -d \ + --name minio \ + -v /run/minio/config:/root/.minio \ + minio/minio:latest \ + -- \ + server /data +``` + +Ensure that Minio has started by watching for `/var/run/minio/config/config.json` to be written: + +``` +while [ ! -e /var/run/minio/config/config.json ]; do + sleep 3 +done +``` + +You now need to collect several pieces of information about your running Minio instance: + +- IP address of the running container: `docker inspect minio | jq -r .[0].NetworkSettings.IPAddress` +- Access key: `jq -r .credential.accessKey /var/run/minio/config/config.json` +- Secret key: `jq -r .credential.secretKey /var/run/minio/config/config.json` + +### Create a bucket + +Like S3, Minio does not automatically create buckets. Use the AWS CLI to create a bucket named `tfe` that will be used to store data: + +```bash +export AWS_ACCESS_KEY_ID="" +export AWS_SECRET_ACCESS_KEY="" + +aws --region us-east-1 --endpoint-url http://:9000 s3 mb s3://tfe +``` + +### Terraform Enterprise installation + +You may now [continue the installation in the browser](/terraform/enterprise/deploy/replicated/install/interactive/installer#continue-installation-in-browser). When you arrive at the Operational Mode choice in the installer, follow these steps: + +1. Choose the "Production" installation type. +1. Choose the _External Services_ operational mode. +1. Provide the required Database URL for the PostgreSQL configuration. +1. Choose "S3" for object storage. +1. Enter the access key and secret access key using the information retrieved from Minio. +1. Provide the endpoint URL, like: `http://:9000`. +1. Enter the name of the bucket you created above (`tfe` in the example). +1. Enter `us-east-1` for the region; this is arbitrary, but must be a valid AWS region. + **Note:** The "Test Authentication" button does not currently work for non-AWS endpoints. +1. Click "Save". + +## Next Steps + +- Familiarize yourself with the various storage backends provided by Minio. +- Make sure you know how to back up and restore the data written to Minio. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/operation-modes-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/operation-modes-partial.mdx new file mode 100644 index 0000000000..6ae2d51f28 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/operation-modes-partial.mdx @@ -0,0 +1,48 @@ + +## Active/Active Mode + +Active/Active mode has the same requirements as External Services, with the additions of an external Redis server, and a fully automated install method. Specifically, Active/Active operational mode has the following additional requirements: + +- Redis server version `6.x` or `7.x` (recommended) +- Redis Cluster is _not_ supported. + +## Mounted Disk + +If you choose to use the Mounted Disk operational mode, Terraform Enterprise will manage its own PostgreSQL database and object storage using a separate directory on the host, with the intention that the directory is configured to store its data on an external disk, such as EBS, iSCSI, etc. + +We strongly suggest following the guidelines below for mounted disk storage. + +### Supported Mounted Disk Types + +The following are **supported** mounted disk types: + +- AWS EBS +- GCP Zonal Persistent Disk +- Azure Disk Storage +- iSCSI +- SAN +- Physically connected disks as in non-cloud hardware + +These disk types provide the necessary reliability and performance for data storage and retrieval in Terraform Enterprise. + +### Unsupported Mounted Disk Types + +The following are **generally not supported** mounted disk types: + +- NFS +- SMB/CIFS + +Terraform Enterprise's storage device or service must be highly reliable and high-speed in both I/O and connectivity to meet performance requirements. Device types in the supported list will usually meet these requirements, but many standard NAS and other device types will not perform at the level required. Only use a NAS or other device type not in the supported list if you are certain it can accommodate these requirements. +For more information about high-speed and highly available storage please see your storage vendor. + +### Mounted Disk Types Not Listed Here + +If the type of mounted disk you wish to use is not in either of the above lists, please contact your HashiCorp representative for clarification on whether that type is supported. + +### Minimum Disk Size + +Terraform Enterprise's minimum disk size is 40GB. + +Depending on your cloud or storage application, you may need to confirm the disk has been resized to at least 40GB. + +For example, with RedHat-flavor (RHEL, CentOS, Oracle Linux) images in Azure Cloud, the storage disk must be resized above the 30GB default after initial boot with `fdisk`, as documented in the Azure knowledge base article [How to: Resize Linux osDisk partition on Azure](https://blogs.msdn.microsoft.com/linuxonazure/2017/04/03/how-to-resize-linux-osdisk-partition-on-azure/). diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/postgres-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/postgres-partial.mdx new file mode 100644 index 0000000000..ca28b21bc3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/postgres-partial.mdx @@ -0,0 +1,46 @@ +To use an external PostgreSQL database with Terraform Enterprise, the following +requirements must be met: + +- A PostgreSQL server such as Amazon RDS for PostgreSQL or a PostgreSQL-compatible server such as Amazon Aurora PostgreSQL must be used. +- The PostgreSQL server version must be one of the following: + - 13.x, 14.4 and up, 15.x or 16.x + - 14.0, 14.1, 14.2, 14.3 are not supported due to a [known defect](https://www.postgresql.org/about/news/postgresql-144-released-2470/) in PostgreSQL. +- A PostgreSQL user must be created with the following permissions on the database: + - The ability to create, modify, and read all tables and indices on all schemas within the database. Usually this is granted if the user is an owner of the database. + - The ability to create extensions. If it is not feasible to have a user with the "CREATE EXTENSION" privilege, then refer to the [Creating Extensions](#creating-extensions) section below for information on creating the necessary extensions. +- The `rails`, `vault`, `registry`, `task_worker`, and `terraform_enterprise` PostgreSQL schemas must be created on the database. These schemas will be automatically created if they do not already exist. + +## Creating Extensions + +If the configured PostgreSQL user does not have permission to create PostgreSQL extensions +(i.e. is not a superuser), then run the following SQL commands to create the proper extensions: + +```sql +CREATE EXTENSION IF NOT EXISTS "hstore" WITH SCHEMA "rails"; +CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "rails"; +CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA "registry"; +``` + +## Connection Parameters + +When providing optional extra keyword parameters for the database connection, +note an additional restriction on the `sslmode` parameter is that only the +`require`, `verify-full`, `verify-ca`, and `disable` values are allowed. For +installations in External Services mode, the default value of `sslmode` is set +to `require`. For installations in Mounted Disk mode, the default value of +`sslmode` is set to `disable`. + +-> **Note:** See the PostgreSQL library documentation for more about [extra parameters related to sslmode](https://www.postgresql.org/docs/12/libpq-ssl.html). Terraform Enterprise provides a certificates file at `/etc/ssl/private/terraform-enterprise/bundle.pem`, which is required by the `verify-full` and `verify-ca` modes. If you are deploying with Replicated, you can add additional certificates with the [CA Custom Bundle](/terraform/enterprise/deploy/replicated/install/interactive/installer#certificate-authority-ca-bundle) setting. + +## PostgreSQL 9.5 to 12 Upgrade + +In Terraform Enterprise v202103-1, the internally-managed PostgreSQL server was upgraded from PostgreSQL 9.5 to PostgreSQL 12. This change only affected +installations in Mounted Disk mode. + +For more details, consult the v202103-1 [release notes](/terraform/enterprise/releases/2021/v202103-1). + +## PostgreSQL 12 to 14 Upgrade + +Terraform Enterprise v202207-1 upgraded the internally-managed PostgresQL server from v12 to v14. This change only affected Mounted disk installations. + +For more details, consult the v202207-1 [release notes](/terraform/enterprise/releases/2022/v202207-1) diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/vault-partial.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/vault-partial.mdx new file mode 100644 index 0000000000..aaea366b72 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/replicated-and-fdo/requirements/vault-partial.mdx @@ -0,0 +1,119 @@ + + +1. Enable the AppRole Auth Method. + +```sh +vault auth enable approle +``` + +1. Enable the Transit Secrets Engine. + +```sh +vault secrets enable transit +``` + +1. Create the `tfe-policy.hcl` file with the following content: + +```hcl +# To renew leases. +path "sys/leases/renew" { + capabilities = ["create", "update"] +} +path "sys/renew" { + capabilities = ["create", "update"] +} + +# To renew tokens. +path "auth/token/renew" { + capabilities = ["create", "update"] +} +path "auth/token/renew-self" { + capabilities = ["create", "update"] +} + +# To perform a login. +path "auth/approle/login" { + capabilities = ["create", "update"] +} + +# To upsert transit keys used for key generation. +path "transit/keys/atlas_*" { + capabilities = ["read", "create", "update"] +} +path "transit/keys/archivist_*" { + capabilities = ["read", "create", "update"] +} + +# To allow for signing using transit keys +path "transit/sign/atlas_*" { + capabilities = ["create", "update"] +} + +# Encryption and decryption of data. +path "transit/encrypt/atlas_*" { + capabilities = ["create", "update"] +} +path "transit/decrypt/atlas_*" { + capabilities = ["create", "update"] +} +path "transit/encrypt/archivist_*" { + capabilities = ["create", "update"] +} +path "transit/decrypt/archivist_*" { + capabilities = ["create", "update"] +} + +# For performing key derivation. +path "transit/datakey/plaintext/archivist_*" { + capabilities = ["create", "update"] +} + +# For backup/restore operations. +path "transit/keys/atlas_*/config" { + capabilities = ["read", "create", "update"] +} +path "transit/backup/atlas_*" { + capabilities = ["read"] +} +path "transit/restore/atlas_*" { + capabilities = ["read", "create", "update"] +} +path "transit/keys/archivist_*/config" { + capabilities = ["read", "create", "update"] +} +path "transit/backup/archivist_*" { + capabilities = ["read"] +} +path "transit/restore/archivist_*" { + capabilities = ["read", "create", "update"] +} + +# For health checks to read the mount table. +path "sys/mounts" { + capabilities = ["read"] +} +``` + +1. Create the `tfe` policy using the `tfe-policy.hcl` policy content. + +```sh +vault policy write tfe tfe-policy.hcl +``` + +1. Create an AppRole with a periodic token using the `tfe` policy. + +```sh +vault write auth/approle/role/tfe policies="tfe" token_period=24h +``` + +1. Fetch the RoleID of the AppRole. This maps back to the `extern_vault_role_id` Terraform Enterprise configuration setting. + +```sh +vault read auth/approle/role/tfe/role-id +``` + +1. Fetch the SecretID of the AppRole. This maps back to the `extern_vault_secret_id` Terraform Enterprise configuration setting. + +```sh +vault write -f auth/approle/role/tfe/secret-id +``` diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/agents.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/agents.mdx new file mode 100644 index 0000000000..0d5cc6c2dc --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/agents.mdx @@ -0,0 +1 @@ +-> **Note:** HCP Terraform **Free** Edition includes one self-hosted agent. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/audit-trails.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/audit-trails.mdx new file mode 100644 index 0000000000..337ad20ea3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/audit-trails.mdx @@ -0,0 +1 @@ +-> **Note:** Audit trails are available in HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. The Audit Trails API is not available for Terraform Enterprise. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/aws-service-catalog.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/aws-service-catalog.mdx new file mode 100644 index 0000000000..1b6cbc45be --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/aws-service-catalog.mdx @@ -0,0 +1 @@ +-> **Note:** The AWS Service Catalog Engine depends on Team management, which is only available in HCP Terraform **Standard** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/ephemeral-workspaces.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/ephemeral-workspaces.mdx new file mode 100644 index 0000000000..16535afd94 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/ephemeral-workspaces.mdx @@ -0,0 +1 @@ +-> **Note:** Ephemeral workspace (automatic destroy runs) functionality is available in HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/health-assessments.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/health-assessments.mdx new file mode 100644 index 0000000000..e8d97b5399 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/health-assessments.mdx @@ -0,0 +1 @@ +-> **Note:** Health assessments are available in HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/manage-module-versions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/manage-module-versions.mdx new file mode 100644 index 0000000000..c357b252a8 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/manage-module-versions.mdx @@ -0,0 +1 @@ +-> **Note:** Module deprecation is available in the HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/nocode.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/nocode.mdx new file mode 100644 index 0000000000..81b9e39aee --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/nocode.mdx @@ -0,0 +1 @@ +-> **Note:** No-code provisioning is available in HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/notifications.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/notifications.mdx new file mode 100644 index 0000000000..6bafcddc9a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/notifications.mdx @@ -0,0 +1 @@ +-> **Note:** Notifications are available in the HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/policies.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/policies.mdx new file mode 100644 index 0000000000..df3e4f31c7 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/policies.mdx @@ -0,0 +1 @@ +-> **Note:** HCP Terraform **Free** Edition includes one policy set of up to five policies. In HCP Terraform **Plus** Edition, you can connect a policy set to a version control repository or create policy set versions via the API. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/project-permissions.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/project-permissions.mdx new file mode 100644 index 0000000000..e100075161 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/project-permissions.mdx @@ -0,0 +1 @@ +-> **Note:** Projects are available to all users, but managing project permissions requires the HCP Terraform **Standard** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/run-tasks.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/run-tasks.mdx new file mode 100644 index 0000000000..aa5d2ce1fd --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/run-tasks.mdx @@ -0,0 +1 @@ +-> **Note:** HCP Terraform **Free** Edition includes one run task integration that you can apply to up to ten workspaces. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/servicenow-catalog.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/servicenow-catalog.mdx new file mode 100644 index 0000000000..c569bee763 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/servicenow-catalog.mdx @@ -0,0 +1 @@ +-> **Note:** The ServiceNow Catalog integration is available in HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/team-management.mdx b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/team-management.mdx new file mode 100644 index 0000000000..df8bcb7f9a --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/docs/partials/tfc-package-callouts/team-management.mdx @@ -0,0 +1 @@ +-> **Note:** Team management is available in HCP Terraform **Standard** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. \ No newline at end of file diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/.gitkeep b/content/terraform-enterprise/v000011-1/v202504-1/img/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-AWS-SingleRegion.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-AWS-SingleRegion.png new file mode 100644 index 0000000000..0fcc522124 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-AWS-SingleRegion.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-Azure-SingleRegion.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-Azure-SingleRegion.png new file mode 100644 index 0000000000..63a581b27c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-Azure-SingleRegion.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-GCP-SingleRegion.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-GCP-SingleRegion.png new file mode 100644 index 0000000000..70b09d0b86 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-GCP-SingleRegion.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-VMware-SingleRegion.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-VMware-SingleRegion.png new file mode 100644 index 0000000000..fc15b94135 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-AA-VMware-SingleRegion.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-AWS-SingleRegion.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-AWS-SingleRegion.png new file mode 100644 index 0000000000..ac8db9a5de Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-AWS-SingleRegion.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-Azure-SingleRegion.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-Azure-SingleRegion.png new file mode 100644 index 0000000000..2a78d15658 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-Azure-SingleRegion.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-GCP-SingleRegion.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-GCP-SingleRegion.png new file mode 100644 index 0000000000..4919af354b Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/RA-TFE-SA-GCP-SingleRegion.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/TFE_In_Kubernetes.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/TFE_In_Kubernetes.png new file mode 100644 index 0000000000..87426ed0ac Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/TFE_In_Kubernetes.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/admin-customization.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/admin-customization.png new file mode 100644 index 0000000000..4fc6214edb Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/admin-customization.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/ado-required-status-check.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/ado-required-status-check.png new file mode 100644 index 0000000000..0a584d490c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/ado-required-status-check.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-server-public-keys.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-server-public-keys.png new file mode 100644 index 0000000000..fa9488c0dd Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-server-public-keys.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-services-application-permissions.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-services-application-permissions.png new file mode 100644 index 0000000000..b50cb74333 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-services-application-permissions.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-services-oauth-policies.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-services-oauth-policies.png new file mode 100644 index 0000000000..1b3221636a Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/azure-devops-services-oauth-policies.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/build-worker.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/build-worker.png new file mode 100644 index 0000000000..36687e2825 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/build-worker.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/download-mocks.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/download-mocks.png new file mode 100644 index 0000000000..4963b475b7 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/download-mocks.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/enc-password-manual-install.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/enc-password-manual-install.png new file mode 100644 index 0000000000..b0597712b5 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/enc-password-manual-install.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/json-viewer-intro.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/json-viewer-intro.png new file mode 100644 index 0000000000..4eb364c55a Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/json-viewer-intro.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/organization-vcs-general-aggregated-status-checks.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/organization-vcs-general-aggregated-status-checks.png new file mode 100644 index 0000000000..f4a82d0b26 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/organization-vcs-general-aggregated-status-checks.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/organization-vcs-general-non-aggregated-status-checks.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/organization-vcs-general-non-aggregated-status-checks.png new file mode 100644 index 0000000000..c328f6ce5c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/organization-vcs-general-non-aggregated-status-checks.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/runs-confirm.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/runs-confirm.png new file mode 100644 index 0000000000..4e0f67cbe4 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/runs-confirm.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-error.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-error.png new file mode 100644 index 0000000000..0f764e1ab5 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-error.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-response.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-response.png new file mode 100644 index 0000000000..57a0c26fc7 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-response.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-sso-enable.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-sso-enable.png new file mode 100644 index 0000000000..0b6324424c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml-sso-enable.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_0.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_0.png new file mode 100644 index 0000000000..f1d0957f39 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_0.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_1.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_1.png new file mode 100644 index 0000000000..7c8bde181a Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_1.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_10.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_10.png new file mode 100644 index 0000000000..857f9fda63 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_10.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_11.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_11.png new file mode 100644 index 0000000000..311dc142aa Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_11.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_12.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_12.png new file mode 100644 index 0000000000..e971e9532d Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_12.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_13.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_13.png new file mode 100644 index 0000000000..7a24bdb50b Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_13.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_14.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_14.png new file mode 100644 index 0000000000..c4d3e67b69 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_14.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_15.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_15.png new file mode 100644 index 0000000000..e6057a6c4b Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_15.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_16.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_16.png new file mode 100644 index 0000000000..cf902ec52e Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_16.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_17.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_17.png new file mode 100644 index 0000000000..b4d16d4f4e Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_17.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_19.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_19.png new file mode 100644 index 0000000000..3cd61b5549 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_19.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_2.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_2.png new file mode 100644 index 0000000000..65c31a20ea Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_2.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_22.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_22.png new file mode 100644 index 0000000000..f843136151 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_22.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_23.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_23.png new file mode 100644 index 0000000000..14c2c5a3bb Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_23.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_26.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_26.png new file mode 100644 index 0000000000..f6b56e70df Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_26.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_27.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_27.png new file mode 100644 index 0000000000..ed7667714f Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_27.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_3.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_3.png new file mode 100644 index 0000000000..50f7f69113 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_3.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_5.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_5.png new file mode 100644 index 0000000000..fdb7f5a03c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_5.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_6.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_6.png new file mode 100644 index 0000000000..aa31386964 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_6.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_8.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_8.png new file mode 100644 index 0000000000..322bd273c0 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_8.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_9.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_9.png new file mode 100644 index 0000000000..9de370346c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/saml_9.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-json-enter-filter.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-json-enter-filter.png new file mode 100644 index 0000000000..aa466692bc Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-json-enter-filter.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-json-quick-filter.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-json-quick-filter.png new file mode 100644 index 0000000000..89d4135702 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-json-quick-filter.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-view-json.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-view-json.png new file mode 100644 index 0000000000..b107dd2647 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sentinel-view-json.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-comments.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-comments.png new file mode 100644 index 0000000000..3c1587f52d Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-comments.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-apikey.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-apikey.png new file mode 100644 index 0000000000..ae921a6629 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-apikey.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-conditional-class-mapping.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-conditional-class-mapping.png new file mode 100644 index 0000000000..203e6d0cf0 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-conditional-class-mapping.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-deactivate-etl.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-deactivate-etl.png new file mode 100644 index 0000000000..7905293a69 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-deactivate-etl.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-design.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-design.png new file mode 100644 index 0000000000..98140a8aad Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-design.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-attribute-mapping.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-attribute-mapping.png new file mode 100644 index 0000000000..ebbb8e21a1 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-attribute-mapping.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-condition-update.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-condition-update.png new file mode 100644 index 0000000000..7fac298ed3 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-condition-update.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-editing-relationship.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-editing-relationship.png new file mode 100644 index 0000000000..33c18f0722 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-editing-relationship.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-setting-relationship.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-setting-relationship.png new file mode 100644 index 0000000000..16b6e5c765 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-etl-setting-relationship.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-import-set.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-import-set.png new file mode 100644 index 0000000000..745a6d302c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-import-set.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-scheduled-import.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-scheduled-import.png new file mode 100644 index 0000000000..c7aa394cbe Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-scheduled-import.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-state-object-url.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-state-object-url.png new file mode 100644 index 0000000000..b687b2a90f Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-state-object-url.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-tags.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-tags.png new file mode 100644 index 0000000000..c5db95a3e3 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-tags.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-team-token-gen.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-team-token-gen.png new file mode 100644 index 0000000000..3e2de6f2b7 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-team-token-gen.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-tfconn.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-tfconn.png new file mode 100644 index 0000000000..34e8d9aef9 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-tfconn.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-schedule.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-schedule.png new file mode 100644 index 0000000000..d4e4701c71 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-schedule.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-tfc.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-tfc.png new file mode 100644 index 0000000000..b6aa99ef80 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-tfc.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-token.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-token.png new file mode 100644 index 0000000000..e65e962b78 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-service-graph-webhook-token.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-store.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-store.png new file mode 100644 index 0000000000..89483f4b2c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-store.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-updated-config.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-updated-config.png new file mode 100644 index 0000000000..30f01cde82 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-updated-config.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-vcs-repository.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-vcs-repository.png new file mode 100644 index 0000000000..7280c87164 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/service-now-vcs-repository.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-add-variables-to-action.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-add-variables-to-action.png new file mode 100644 index 0000000000..a8347388c9 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-add-variables-to-action.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-adjust-script-variables.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-adjust-script-variables.png new file mode 100644 index 0000000000..90e1e4ebc3 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-adjust-script-variables.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-configure-item.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-configure-item.png new file mode 100644 index 0000000000..461b290b2d Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-configure-item.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copied-item.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copied-item.png new file mode 100644 index 0000000000..f29726c373 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copied-item.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copy-action.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copy-action.png new file mode 100644 index 0000000000..71ec9c7d0d Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copy-action.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copy-flow.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copy-flow.png new file mode 100644 index 0000000000..a1632b6c32 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-copy-flow.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-edit-flow.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-edit-flow.png new file mode 100644 index 0000000000..2c21653e95 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-edit-flow.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-fill-new-action-step.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-fill-new-action-step.png new file mode 100644 index 0000000000..bf51f5f65b Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-fill-new-action-step.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-get-variables.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-get-variables.png new file mode 100644 index 0000000000..94821fc4da Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-get-variables.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-new-varset-form.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-new-varset-form.png new file mode 100644 index 0000000000..d6bf2f3d65 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-new-varset-form.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-new-varset.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-new-varset.png new file mode 100644 index 0000000000..051ac6eba3 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-new-varset.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-open-action.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-open-action.png new file mode 100644 index 0000000000..fdc4f97274 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-open-action.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-original-flow.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-original-flow.png new file mode 100644 index 0000000000..2456b8bbe2 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-original-flow.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-process-engine.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-process-engine.png new file mode 100644 index 0000000000..979d5c3a70 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-process-engine.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-remove-example-variables-from-action.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-remove-example-variables-from-action.png new file mode 100644 index 0000000000..09d558eb39 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-remove-example-variables-from-action.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-remove-example-variables.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-remove-example-variables.png new file mode 100644 index 0000000000..214822eb84 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-remove-example-variables.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-rename-action.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-rename-action.png new file mode 100644 index 0000000000..cb18e2b96d Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-rename-action.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-replace-action.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-replace-action.png new file mode 100644 index 0000000000..2757f6cdce Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-replace-action.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-service-portal.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-service-portal.png new file mode 100644 index 0000000000..d54402d3ef Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-service-portal.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-update-process-engine.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-update-process-engine.png new file mode 100644 index 0000000000..1c3cbfdce8 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-update-process-engine.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-variables.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-variables.png new file mode 100644 index 0000000000..0a7aa95de8 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/servicenow-catalog-variables.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-add-application.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-add-application.png new file mode 100644 index 0000000000..9345cf709a Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-add-application.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-app-registration.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-app-registration.png new file mode 100644 index 0000000000..1f1a2eb368 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-app-registration.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-configuration.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-configuration.png new file mode 100644 index 0000000000..d0f15ff59c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-configuration.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-manifest-approles.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-manifest-approles.png new file mode 100644 index 0000000000..60c2dbd5c3 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-manifest-approles.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-manifest-devapprole.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-manifest-devapprole.png new file mode 100644 index 0000000000..8aa4fb09b2 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-manifest-devapprole.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-new-application-form.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-new-application-form.png new file mode 100644 index 0000000000..cfb70cbf26 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-new-application-form.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-role-assignment.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-role-assignment.png new file mode 100644 index 0000000000..94187a8309 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-role-assignment.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-signing-certificate.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-signing-certificate.png new file mode 100644 index 0000000000..a29c7159df Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-signing-certificate.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-sso-method.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-sso-method.png new file mode 100644 index 0000000000..3178fe6897 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-sso-method.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-tfe-saml-settings.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-tfe-saml-settings.png new file mode 100644 index 0000000000..157c101f18 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-tfe-saml-settings.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-urls.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-urls.png new file mode 100644 index 0000000000..562c46896e Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-urls.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-user-claims-memberof.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-user-claims-memberof.png new file mode 100644 index 0000000000..b631bfc5ed Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-user-claims-memberof.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-user-claims-name-identifier.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-user-claims-name-identifier.png new file mode 100644 index 0000000000..bb36f31154 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-aad-saml-user-claims-name-identifier.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-access.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-access.png new file mode 100644 index 0000000000..9e0fe62c44 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-access.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-configuration.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-configuration.png new file mode 100644 index 0000000000..dae5d8bd36 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-configuration.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-info.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-info.png new file mode 100644 index 0000000000..70284cbc57 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-info.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-parameters-memberof.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-parameters-memberof.png new file mode 100644 index 0000000000..286a70242c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-parameters-memberof.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-parameters.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-parameters.png new file mode 100644 index 0000000000..ddb74bb17e Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-parameters.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-sso-certificate.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-sso-certificate.png new file mode 100644 index 0000000000..81ee902aae Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-sso-certificate.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-sso.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-sso.png new file mode 100644 index 0000000000..c4ec12f6f1 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-sso.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-users-fields.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-users-fields.png new file mode 100644 index 0000000000..72b2f72d85 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-users-fields.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-users.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-users.png new file mode 100644 index 0000000000..c93030ad62 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/sso-onelogin-users.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/terraform-cloud-run-tasks-diagram.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/terraform-cloud-run-tasks-diagram.png new file mode 100644 index 0000000000..f07ba3396f Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/terraform-cloud-run-tasks-diagram.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfc-explorer-health.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfc-explorer-health.png new file mode 100644 index 0000000000..de8f58bf5b Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfc-explorer-health.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-console-settings.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-console-settings.png new file mode 100644 index 0000000000..22c2a22e43 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-console-settings.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-dashboard.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-dashboard.png new file mode 100644 index 0000000000..7993bcb2bb Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-dashboard.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-data-flow-arch.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-data-flow-arch.png new file mode 100644 index 0000000000..ccd2820773 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-data-flow-arch.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-http-proxy.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-http-proxy.png new file mode 100644 index 0000000000..f83cb087a2 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-http-proxy.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-proxy-bypass.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-proxy-bypass.png new file mode 100644 index 0000000000..8da8a594b7 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-proxy-bypass.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-support.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-support.png new file mode 100644 index 0000000000..085f8b773a Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe-support.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe_console-custom_agent_image_tag.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe_console-custom_agent_image_tag.png new file mode 100644 index 0000000000..a6e53eda0d Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe_console-custom_agent_image_tag.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe_console-custom_image_tag.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe_console-custom_image_tag.png new file mode 100644 index 0000000000..56d0e05594 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tfe_console-custom_image_tag.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-ca.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-ca.png new file mode 100644 index 0000000000..85aabb30f0 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-ca.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-ciphers.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-ciphers.png new file mode 100644 index 0000000000..bd63cb882c Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-ciphers.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-hsts.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-hsts.png new file mode 100644 index 0000000000..b1070768d4 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-hsts.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-installer.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-installer.png new file mode 100644 index 0000000000..d85db49d02 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-installer.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-self-signed.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-self-signed.png new file mode 100644 index 0000000000..28c3d02913 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-self-signed.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-server-path.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-server-path.png new file mode 100644 index 0000000000..e44f027ab6 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-server-path.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-upload.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-upload.png new file mode 100644 index 0000000000..dce3e176cd Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-upload.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-versions.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-versions.png new file mode 100644 index 0000000000..94eb5b0bf3 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/tls-versions.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/token.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/token.png new file mode 100644 index 0000000000..a7fd6c3617 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/token.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/vmware-mounted-disk-infrastructure-diagram.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/vmware-mounted-disk-infrastructure-diagram.png new file mode 100644 index 0000000000..86ce040440 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/vmware-mounted-disk-infrastructure-diagram.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/workspace-net-infra-combined.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/workspace-net-infra-combined.png new file mode 100644 index 0000000000..de0d770d54 Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/workspace-net-infra-combined.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/img/docs/workspace-net-infra-split.png b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/workspace-net-infra-split.png new file mode 100644 index 0000000000..33bb2d03fb Binary files /dev/null and b/content/terraform-enterprise/v000011-1/v202504-1/img/docs/workspace-net-infra-split.png differ diff --git a/content/terraform-enterprise/v000011-1/v202504-1/redirects.jsonc b/content/terraform-enterprise/v000011-1/v202504-1/redirects.jsonc new file mode 100644 index 0000000000..5b17d05fe3 --- /dev/null +++ b/content/terraform-enterprise/v000011-1/v202504-1/redirects.jsonc @@ -0,0 +1,784 @@ +/** + * Redirects in this file are intended to be for documentation content only. The redirects will be applied to developer.hashicorp.com. + */ + +[ + // FDO/Replicated Rework + // Redirect from the beta to the GA docs + // versioned redirect (keeping this generic because anything going to the beta should be redirected to the GA) + { + "source": + "/terraform/enterprise/:version(v\\d{6}-\\d)/flexible-deployments-beta/:slug*", + "destination": "/terraform/enterprise/flexible-deployments/", + "permanent": true, + }, + // for those who saved the page directly + // UPDATE: redirecting to refactored docs v202407 + { + "source": "/terraform/enterprise/flexible-deployments-beta/admin/support", + "destination": "/terraform/enterprise/deploy/troubleshoot/contact-support", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments-beta", + "destination": "/terraform/enterprise/deploy", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/install/requirements/docker", + "destination": + "/terraform/enterprise/deploy/docker", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/install/requirements/kubernetes", + "destination": + "/terraform/enterprise/deploy/kubernetes", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/replicated-migration", + "destination": "/terraform/enterprise/deploy/replicated-migration", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/install/requirements/license", + "destination": + "/terraform/enterprise/deploy/configuration/license", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments-beta/install/docker", + "destination": + "/terraform/enterprise/deploy/docker", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/install/kubernetes", + "destination": + "/terraform/enterprise/deploy/kubernetes", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/install/initial-admin-user", + "destination": + "/terraform/enterprise/deploy/initial-admin-user", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments-beta/install/scaling", + "destination": + "/terraform/enterprise/deploy/kubernetes/scale", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/install/configuration", + "destination": + "/terraform/enterprise/deploy/reference/configuration", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/monitoring/observability/logs", + "destination": + "/terraform/enterprise/deploy/manage/monitor", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/monitoring/observability/metrics", + "destination": + "/terraform/enterprise/deploy/manage/monitor", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/monitoring/startup-checks", + "destination": + "/terraform/enterprise/deploy/reference/startup-checks", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments-beta/admin", + "destination": "/terraform/enterprise/deploy/manage", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/admin/admin-cli/admin-cli", + "destination": + "/terraform/enterprise/deploy/reference/cli", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/admin/admin-cli/backup-restore", + "destination": + "/terraform/enterprise/deploy/manage/backup-restore", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/flexible-deployments-beta/requirements/network", + "destination": + "/terraform/enterprise/deploy/configuration/network", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments-beta/troubleshooting", + "destination": "/terraform/enterprise/deploy/troubleshoot", + "permanent": true, + }, + // REPLICATED DOCS + // Requirements + // If the version is anything in 2018-2022, or 2023 *before* 09-01 (when FDO went live) then we want to omit "replicated" from the URL + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/requirements/docker_engine", + "destination": "/terraform/enterprise/:version/requirements/docker", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/requirements/:slug*", + "destination": "/terraform/enterprise/:version/requirements/:slug*", + "permanent": true, + }, + // for those who saved the page directly + { + "source": "/terraform/enterprise/requirements/credentials", + "destination": "/terraform/enterprise/replicated/requirements/credentials", + "permanent": true, + }, + { + "source": "/terraform/enterprise/requirements/hardware", + "destination": "/terraform/enterprise/replicated/requirements/hardware", + "permanent": true, + }, + { + "source": "/terraform/enterprise/requirements/os-specific/supported-os", + "destination": + "/terraform/enterprise/replicated/requirements/os-specific/supported-os", + "permanent": true, + }, + { + "source": "/terraform/enterprise/requirements/os-specific/rhel-requirements", + "destination": + "/terraform/enterprise/replicated/requirements/os-specific/rhel-requirements", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/requirements/os-specific/centos-requirements", + "destination": + "/terraform/enterprise/replicated/requirements/os-specific/centos-requirements", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/requirements/data-storage/operational-mode-requirements", + "destination": + "/terraform/enterprise/replicated/requirements/data-storage/operational-mode-requirements", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/requirements/data-storage/postgres-requirements", + "destination": + "/terraform/enterprise/replicated/requirements/data-storage/postgres-requirements", + "permanent": true, + }, + { + "source": "/terraform/enterprise/requirements/data-storage/minio-setup-guide", + "destination": + "/terraform/enterprise/replicated/requirements/data-storage/minio-setup-guide", + "permanent": true, + }, + { + "source": "/terraform/enterprise/requirements/network", + "destination": "/terraform/enterprise/replicated/requirements/network", + "permanent": true, + }, + { + "source": "/terraform/enterprise/requirements/docker", + "destination": "/terraform/enterprise/replicated/requirements/docker_engine", + "permanent": true, + }, + { + "source": "/terraform/enterprise/requirements/data-storage/vault", + "destination": + "/terraform/enterprise/flexible-deployments/install/requirements/vault", + "permanent": true, + }, + { + "source": "/terraform/enterprise/operational-modes", + "destination": "/terraform/enterprise/replicated/install/operation-modes", + "permanent": true, + }, + // Installation + // versioned redirects + // If the version is anything in 2018-2022, or 2023 *before* 09-01 (when FDO went live) then we want to omit "replicated" from the URL + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/install/:slug*", + "destination": "/terraform/enterprise/:version/install/:slug*", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/install/operation-modes", + "destination": "/terraform/enterprise/:version/operational-modes", + "permanent": true, + }, + // those who saved the page directly + { + "source": "/terraform/enterprise/install/pre-install-checklist", + "destination": + "/terraform/enterprise/replicated/install/pre-install-checklist", + "permanent": true, + }, + { + "source": "/terraform/enterprise/install/interactive/installer", + "destination": + "/terraform/enterprise/replicated/install/interactive/installer", + "permanent": true, + }, + { + "source": "/terraform/enterprise/install/interactive/config", + "destination": "/terraform/enterprise/replicated/install/interactive/config", + "permanent": true, + }, + { + "source": "/terraform/enterprise/install/automated/automating-the-installer", + "destination": + "/terraform/enterprise/replicated/install/automated/automating-the-installer", + "permanent": true, + }, + { + "source": "/terraform/enterprise/install/automated/active-active", + "destination": + "/terraform/enterprise/replicated/install/automated/active-active", + "permanent": true, + }, + { + "source": "/terraform/enterprise/install/automated/automating-initial-user", + "destination": + "/terraform/enterprise/replicated/install/automated/automating-initial-user", + "permanent": true, + }, + { + "source": "/terraform/enterprise/install/automated/encryption-password", + "destination": + "/terraform/enterprise/replicated/install/automated/encryption-password", + "permanent": true, + }, + { + "source": "/terraform/enterprise/install/uninstall", + "destination": "/terraform/enterprise/replicated/install/uninstall", + "permanent": true, + }, + // Administration + // versioned redirects for administration and application administration + // versioned redirect for license + // If the version is anything in 2018-2022, or 2023 *before* 09-01 (when FDO went live) then we want to omit "replicated" from the URL + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/administration/license/:slug*", + "destination": "/terraform/enterprise/:version/admin/application/:slug*", + "permanent": true, + }, + // version redirect for all infrastructure pages from replicated + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/administration/infrastructure/:slug*", + "destination": "/terraform/enterprise/:version/admin/infrastructure/:slug*", + "permanent": true, + }, + // version redirect for all administration application pages from replicated + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/application-administration/:slug*", + "destination": "/terraform/enterprise/:version/admin/application/:slug*", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/administration/:slug*", + "destination": "/terraform/enterprise/:version/admin/:slug*", + "permanent": true, + }, + // those who saved the page directly + { + "source": "/terraform/enterprise/admin", + "destination": "/terraform/enterprise/replicated/administration", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/agents-on-tfe", + "destination": + "/terraform/enterprise/application-administration/agents-on-tfe", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/infrastructure/automated-recovery", + "destination": + "/terraform/enterprise/replicated/administration/infrastructure/automated-recovery", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/infrastructure/upgrades", + "destination": + "/terraform/enterprise/replicated/administration/infrastructure/upgrades", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/infrastructure/backup-restore", + "destination": + "/terraform/enterprise/replicated/administration/infrastructure/backup-restore", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/infrastructure/admin-cli", + "destination": + "/terraform/enterprise/replicated/administration/infrastructure/admin-cli", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/admin/infrastructure/worker-to-agent-migration", + "destination": + "/terraform/enterprise/replicated/administration/infrastructure/worker-to-agent-migration", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/infrastructure/consolidated-services", + "destination": + "/terraform/enterprise/replicated/administration/infrastructure/consolidated-services", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/admin-access", + "destination": + "/terraform/enterprise/application-administration/admin-access", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/general", + "destination": "/terraform/enterprise/application-administration/general", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/customization", + "destination": + "/terraform/enterprise/application-administration/customization", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/integration", + "destination": "/terraform/enterprise/application-administration/integration", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/opa-tool-versions", + "destination": + "/terraform/enterprise/application-administration/opa-tool-versions", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/github-app-integration", + "destination": + "/terraform/enterprise/application-administration/github-app-integration", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/resources", + "destination": "/terraform/enterprise/application-administration/resources", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/registry-sharing", + "destination": + "/terraform/enterprise/application-administration/registry-sharing", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/application/update-tfe-license", + "destination": + "/terraform/enterprise/replicated/administration/license/update-tfe-license", + "permanent": true, + }, + { + "source": + "/terraform/enterprise/admin/application/automated-license-utilization-reporting", + "destination": + "/terraform/enterprise/replicated/administration/license/automated-license-utilization-reporting", + "permanent": true, + }, + // Architecture + // versioned redirects + // If the version is anything in 2018-2022, or 2023 *before* 09-01 (when FDO went live) then we want to omit "replicated" from the URL + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/architecture/reference-architecture/:slug*", + "destination": "/terraform/enterprise/:version/reference-architecture/:slug*", + "permanent": true, + }, + // for those who saved the page directly + { + "source": "/terraform/enterprise/reference-architecture", + "destination": + "/terraform/enterprise/replicated/architecture/reference-architecture", + "permanent": true, + }, + { + "source": "/terraform/enterprise/reference-architecture/aws", + "destination": + "/terraform/enterprise/replicated/architecture/reference-architecture/aws", + "permanent": true, + }, + { + "source": "/terraform/enterprise/reference-architecture/azure", + "destination": + "/terraform/enterprise/replicated/architecture/reference-architecture/azure", + "permanent": true, + }, + { + "source": "/terraform/enterprise/reference-architecture/gcp", + "destination": + "/terraform/enterprise/replicated/architecture/reference-architecture/gcp", + "permanent": true, + }, + { + "source": "/terraform/enterprise/reference-architecture/vmware", + "destination": + "/terraform/enterprise/replicated/architecture/reference-architecture/vmware", + "permanent": true, + }, + // System Overview + // versioned redirects + // If the version is anything in 2018-2022, or 2023 *before* 09-01 (when FDO went live) then we want to omit "replicated" from the URL + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/architecture/system-overview/:slug*", + "destination": "/terraform/enterprise/:version/system-overview/:slug*", + "permanent": true, + }, + // for those who saved the page directly + { + "source": "/terraform/enterprise/system-overview", + "destination": + "/terraform/enterprise/replicated/architecture/system-overview", + "permanent": true, + }, + { + "source": "/terraform/enterprise/system-overview/reliability-availability", + "destination": + "/terraform/enterprise/replicated/architecture/system-overview/reliability-availability", + "permanent": true, + }, + { + "source": "/terraform/enterprise/system-overview/capacity", + "destination": + "/terraform/enterprise/replicated/architecture/system-overview/capacity", + "permanent": true, + }, + { + "source": "/terraform/enterprise/system-overview/security-model", + "destination": + "/terraform/enterprise/replicated/architecture/system-overview/security-model", + "permanent": true, + }, + { + "source": "/terraform/enterprise/system-overview/data-security", + "destination": + "/terraform/enterprise/replicated/architecture/system-overview/data-security", + "permanent": true, + }, + // Monitoring + // versioned redirects + // If the version is anything in 2018-2022, or 2023 *before* 09-01 (when FDO went live) then we want to omit "replicated" from the URL + { + "source": + "/terraform/enterprise/:version(v201[8-9]\\d{2}-\\d{1}|v202[0-2]\\d{2}-\\d{1}|v20230[1-8](?:-(?!09-01)\\d{1})?)/replicated/monitoring/:slug*", + "destination": "/terraform/enterprise/:version/admin/infrastructure/:slug*", + "permanent": true, + }, + // for those who saved the page directly + { + "source": "/terraform/enterprise/admin/infrastructure/logging", + "destination": "/terraform/enterprise/replicated/monitoring/logging", + "permanent": true, + }, + { + "source": "/terraform/enterprise/admin/infrastructure/monitoring", + "destination": "/terraform/enterprise/replicated/monitoring/monitoring", + "permanent": true, + }, + // Redirect content under ~/replicated/install folder to ~/deploy/replicated/install + { + "source": "/terraform/enterprise/replicated/install/:slug*", + "destination": "/terraform/enterprise/deploy/replicated/install/:slug*", + "permanent": true, + }, + // Redirect content under ~/replicated/requirements folder to ~/deploy/replicated/requirements + { + "source": "/terraform/enterprise/replicated/requirements/:slug*", + "destination": "/terraform/enterprise/deploy/replicated/requirements/:slug*", + "permanent": true, + }, + // Redirect content under ~/replicated/architecture folder to ~/deploy/replicated/architecture + { + "source": "/terraform/enterprise/replicated/architecture/:slug*", + "destination": "/terraform/enterprise/deploy/replicated/architecture/:slug*", + "permanent": true, + }, + // Redirect content under ~/replicated/administration folder to ~/deploy/replicated/administration + { + "source": "/terraform/enterprise/replicated/administration/:slug*", + "destination": "/terraform/enterprise/deploy/replicated/administration/:slug*", + "permanent": true, + }, + // Redirect content under ~/replicated/monitoring folder to ~/deploy/replicated/monitoring + { + "source": "/terraform/enterprise/replicated/monitoring/:slug*", + "destination": "/terraform/enterprise/deploy/replicated/monitoring/:slug*", + "permanent": true, + }, + { + "source": "/terraform/enterprise/replicated/replicated-migration", + "destination": "/terraform/enterprise/deploy/replicated-migration", + "permanent": true, + }, + // Redirect FDO topics to /deploy + { + "source": "/terraform/enterprise/flexible-deployments", + "destination": "/terraform/enterprise/deploy", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/configuration", + "destination": "/terraform/enterprise/deploy/reference/configuration", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install", + "destination": "/terraform/enterprise/deploy", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/podman/requirements", + "destination": "/terraform/enterprise/deploy/podman", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/podman/install", + "destination": "/terraform/enterprise/deploy/podman", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/docker/requirements", + "destination": "/terraform/enterprise/deploy/docker", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/docker/install", + "destination": "/terraform/enterprise/deploy/docker", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/scaling/docker", + "destination": "/terraform/enterprise/deploy/docker/scale", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/kubernetes/openshift", + "destination": "/terraform/enterprise/deploy/openshift", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/kubernetes/install", + "destination": "/terraform/enterprise/deploy/kubernetes", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/kubernetes/requirements", + "destination": "/terraform/enterprise/deploy/kubernetes", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/scaling/kubernetes", + "destination": "/terraform/enterprise/deploy/kubernetes/scale", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/custom-image", + "destination": "/terraform/enterprise/deploy/custom-image", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/operation-modes", + "destination": "/terraform/enterprise/deploy/configuration/storage/configure-mode", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/requirements/data-storage/operational-mode-requirements", + "destination": "/terraform/enterprise/deploy/configuration/storage/configure-mode", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/requirements/data-storage/postgres-requirements", + "destination": "/terraform/enterprise/deploy/configuration/storage/connect-database", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/requirements/vault", + "destination": "/terraform/enterprise/deploy/configuration/storage/connect-vault", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/requirements/network", + "destination": "/terraform/enterprise/deploy/configuration/network", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/requirements/license", + "destination": "/terraform/enterprise/deploy/configuration/license", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/install/initial-admin-user", + "destination": "/terraform/enterprise/deploy/initial-admin-user", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/admin/admin-cli/admin-cli", + "destination": "/terraform/enterprise/deploy/reference/cli", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/admin/admin-cli/backup-restore", + "destination": "/terraform/enterprise/deploy/manage/backup-restore", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/admin/admin-cli/cli-access", + "destination": "/terraform/enterprise/deploy/manage/access-cli", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/admin", + "destination": "/terraform/enterprise/deploy/manage", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/admin/license", + "destination": "/terraform/enterprise/deploy/manage/license-report", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/admin/upgrade", + "destination": "/terraform/enterprise/deploy/manage/upgrade", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/architecture/system/data-security", + "destination": "/terraform/enterprise/deploy/reference/data-security", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/architecture/system/security-model", + "destination": "/terraform/enterprise/deploy/reference/application-security", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/architecture/reference", + "destination": "/terraform/enterprise/deploy/reference/architecture", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/monitoring/startup-checks", + "destination": "/terraform/enterprise/deploy/reference/startup-checks", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/monitoring/observability/logs", + "destination": "/terraform/enterprise/deploy/manage/monitor", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/monitoring/observability/metrics", + "destination": "/terraform/enterprise/deploy/manage/monitor", + "permanent": true, + }, + { + "source": "/terraform/enterprise/flexible-deployments/troubleshooting", + "destination": "/terraform/enterprise/deploy/troubleshoot", + "permanent": true, + }, + { + "source": "/terraform/enterprise/support", + "destination": "/terraform/enterprise/deploy/troubleshoot/contact-support", + "permanent": true, + }, + // redirects for deploying to Nomad + { + "source": "/terraform/enterprise/flexible-deployments/install/nomad/:slug", + "destination": "/terraform/enterprise/deploy/nomad", + "permanent": true, + }, + // Redirect to older page + // Policy enforcement changes related to pre-written Sentinel policies + { + "source": "/terraform/enterprise/policy-enforcement/sentinel", + "destination": "/terraform/enterprise/policy-enforcement/define-policies/sentinel", + "permanent": true + }, + { + "source": "/terraform/enterprise/policy-enforcement/opa", + "destination": "/terraform/enterprise/policy-enforcement/define-policies/opa", + "permanent": true + }, + { + "source": "/terraform/enterprise/policy-enforcement/sentinel/vcs", + "destination": "/terraform/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs", + "permanent": true + }, + { + "source": "/terraform/enterprise/policy-enforcement/opa/vcs", + "destination": "/terraform/enterprise/policy-enforcement/manage-policy-sets/opa-vcs", + "permanent": true + }, + { + "source": "/terraform/enterprise/policy-enforcement/policy-results", + "destination": "/terraform/enterprise/policy-enforcement/view-results", + "permanent": true + }, + { + "source": "/terraform/enterprise/policy-enforcement/sentinel/json", + "destination": "/terraform/enterprise/policy-enforcement/view-results/json", + "permanent": true + }, + { + "source": "/terraform/enterprise/policy-enforcement/sentinel/mock", + "destination": "/terraform/enterprise/policy-enforcement/test-sentinel", + "permanent": true + }, + { + "source": "/terraform/enterprise/policy-enforcement/sentinel/import/:slug", + "destination": "/terraform/enterprise/policy-enforcement/import-reference/:slug", + "permanent": true + }, + // Relocate pre-written Sentinel policies topic + { + "source": "/terraform/enterprise/policy-enforcement/define-policies/prewritten-sentinel", + "destination": "/terraform/enterprise/policy-enforcement/prewritten-sentinel", + "permanent": true + }, +]