documentation for agent registry

Author: Chris-Paris-HashiCorp

CHANGELOG.md

@@ -6,6 +6,7 @@ BREAKING CHANGES:
 
 FEATURES:
 
+* **New Resource**: `vault_agent_registration` for managing agent registrations in Vault Enterprise. Allows registering Vault agents with specific identity entities and configuring ceiling policies that limit maximum agent permissions. Requires Vault 2.0.0+.
 * **New Resources**: `vault_rotation_policy` for managing rotation policies. Requires Vault 2.0.0+. ([#2844](https://github.com/hashicorp/terraform-provider-vault/pull/2844))
 * Add support for `vault_quota_config` resource. ([#2837](https://github.com/hashicorp/terraform-provider-vault/pull/2837))
 * **New Resources**: Add support for Vault Key Management secrets engine with resources for managing KMS providers (AWS KMS, Azure Key Vault, GCP Cloud KMS), cryptographic keys, key distribution, replication, and rotation (Vault Enterprise). ([#2802](https://github.com/hashicorp/terraform-provider-vault/pull/2802))

website/docs/r/agent_registration.html.md

@@ -0,0 +1,187 @@
+---
+layout: "vault"
+page_title: "Vault: vault_agent_registration resource"
+sidebar_current: "docs-vault-resource-sys-agent-registration"
+description: |-
+  Manages agent registrations in Vault Enterprise.
+---
+
+# vault\_agent\_registration
+
+Manages agent registrations in Vault Enterprise. Agent registration allows you to register Vault agents with specific identity entities and configure ceiling policies that limit the maximum permissions an agent can obtain.
+
+~> **Important** This resource is only available in Vault Enterprise and requires Vault 2.0.0 or later.
+
+## Example Usage
+
+### Basic Agent Registration
+
+```hcl
+resource "vault_identity_entity" "agent" {
+  name     = "my-agent-entity"
+  policies = ["default"]
+}
+
+resource "vault_agent_registration" "example" {
+  display_name = "my-agent"
+  entity_id    = vault_identity_entity.agent.id
+}
+```
+
+### Agent Registration with Ceiling Policies
+
+```hcl
+resource "vault_policy" "agent_ceiling" {
+  name = "agent-ceiling-policy"
+  policy = <<EOT
+path "secret/data/*" {
+  capabilities = ["read"]
+}
+
+path "auth/token/renew-self" {
+  capabilities = ["update"]
+}
+EOT
+}
+
+resource "vault_identity_entity" "agent" {
+  name     = "my-agent-entity"
+  policies = ["default"]
+}
+
+resource "vault_agent_registration" "example" {
+  display_name               = "my-agent"
+  entity_id                  = vault_identity_entity.agent.id
+  ceiling_policy_identifiers = [vault_policy.agent_ceiling.name]
+  description                = "Production agent for application X"
+}
+```
+
+### Agent Registration Without Default Ceiling Policy
+
+```hcl
+resource "vault_identity_entity" "agent" {
+  name = "my-agent-entity"
+}
+
+resource "vault_agent_registration" "example" {
+  display_name              = "my-agent"
+  entity_id                 = vault_identity_entity.agent.id
+  no_default_ceiling_policy = true
+}
+```
+
+### Agent Registration in a Namespace
+
+```hcl
+resource "vault_namespace" "app" {
+  path = "application"
+}
+
+resource "vault_identity_entity" "agent" {
+  namespace = vault_namespace.app.path
+  name      = "my-agent-entity"
+  policies  = ["default"]
+}
+
+resource "vault_agent_registration" "example" {
+  namespace    = vault_namespace.app.path
+  display_name = "my-agent"
+  entity_id    = vault_identity_entity.agent.id
+}
+```
+
+### Agent Registration with Multiple Ceiling Policies
+
+```hcl
+resource "vault_policy" "secrets_read" {
+  name = "secrets-read"
+  policy = <<EOT
+path "secret/data/*" {
+  capabilities = ["read"]
+}
+EOT
+}
+
+resource "vault_policy" "auth_renew" {
+  name = "auth-renew"
+  policy = <<EOT
+path "auth/token/renew-self" {
+  capabilities = ["update"]
+}
+EOT
+}
+
+resource "vault_identity_entity" "agent" {
+  name     = "my-agent-entity"
+  policies = ["default"]
+}
+
+resource "vault_agent_registration" "example" {
+  display_name = "my-agent"
+  entity_id    = vault_identity_entity.agent.id
+  ceiling_policy_identifiers = [
+    vault_policy.secrets_read.name,
+    vault_policy.auth_renew.name,
+  ]
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `namespace` - (Optional) The namespace to provision the resource in.
+  The value should not contain leading or trailing forward slashes.
+  The `namespace` is always relative to the provider's configured [namespace](/docs/providers/vault/index.html#namespace).
+  *Available only for Vault Enterprise*.
+
+* `display_name` - (Required) The display name for the agent registration. This is used as the unique identifier for the agent. Changing this will force a new resource to be created.
+
+* `entity_id` - (Required) The ID of the identity entity to associate with this agent registration. The entity must exist before creating the agent registration.
+
+* `ceiling_policy_identifiers` - (Optional) A list of policy names that define the maximum permissions this agent can obtain. These policies act as a ceiling - the agent cannot obtain permissions beyond what these policies allow, even if the entity or token policies would grant more permissions. By default, Vault applies a default ceiling policy unless `no_default_ceiling_policy` is set to `true`.
+
+* `no_default_ceiling_policy` - (Optional) When set to `true`, prevents Vault from applying the default ceiling policy to this agent. This allows you to have complete control over the agent's ceiling policies. Defaults to `false`.
+
+* `description` - (Optional) A human-readable description of the agent registration. This field is for documentation purposes and does not affect the agent's behavior.
+
+## Attributes Reference
+
+In addition to the arguments above, the following attributes are exported:
+
+* `id` - The unique identifier for the agent registration. This is a GUID-like identifier automatically generated by Vault.
+
+* `creation_time` - The timestamp when the agent registration was created, in RFC3339 format.
+
+* `last_updated_time` - The timestamp when the agent registration was last updated, in RFC3339 format.
+
+## Import
+
+Agent registrations can be imported using the `display_name`, e.g.
+
+```
+$ terraform import vault_agent_registration.example my-agent
+```
+
+For agent registrations in a namespace, use the format `namespace/display_name`:
+
+```
+$ terraform import vault_agent_registration.example application/my-agent
+```
+
+## Notes
+
+* **Ceiling Policies**: Ceiling policies define the maximum permissions an agent can obtain. Even if the associated entity or token policies grant broader permissions, the agent will be limited to the intersection of all applicable policies and the ceiling policies.
+
+* **Default Ceiling Policy**: By default, Vault applies a default ceiling policy to agent registrations. This policy is automatically filtered out when reading the resource state, so only user-specified ceiling policies appear in the `ceiling_policy_identifiers` attribute.
+
+* **Entity Requirement**: The identity entity specified in `entity_id` must exist before creating the agent registration. The entity defines the base identity for the agent.
+
+* **Display Name Uniqueness**: The `display_name` must be unique within the namespace. Attempting to create multiple agent registrations with the same display name will result in an error.
+
+* **Immutable Display Name**: Changing the `display_name` requires destroying and recreating the agent registration, as it serves as the unique identifier.
+
+* **Enterprise Feature**: Agent registration is only available in Vault Enterprise. Attempting to use this resource with Vault Community Edition will result in an error.
+
+* **Version Requirement**: This resource requires Vault 1.18.0 or later.