TFVP: implement support for Agent Registry

[Chris-Paris-HashiCorp]

Description

Jira: https://hashicorp.atlassian.net/browse/VAULT-44159

Checklist

• Added CHANGELOG entry (only for user-facing changes)
• Acceptance tests where run against all supported Vault Versions

Output from acceptance testing:

$ make testacc TESTARGS='-run=TestAccXXX'

...

Community Note

• Please vote on this pull request by adding a 👍 reaction to the original pull request comment to help the community and maintainers prioritize this request
• Please do not leave "+1" comments, they generate extra noise for pull request followers and do not help prioritize the request

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.

• If applicable, I've documented the impact of any changes to security controls.

  Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.

[hashicorp-cla-app]

All committers have signed the CLA.

[hashicorp-cla-app]

Thank you for your submission! We require that all contributors sign our Contributor License Agreement ("CLA") before we can accept the contribution. Read and sign the agreement

Learn more about why HashiCorp requires a CLA and what the CLA includes

---

Chris Paris seems not to be a GitHub user.
You need a GitHub account to be able to sign the CLA.
If you have already a GitHub account, please add the email address used for this commit to your account.

_{Have you signed the CLA already but the status is still pending? Recheck it.}

[Chris-Paris-HashiCorp]

Agent Registration Resource Implementation

Overview

This document describes the implementation of the vault_agent_registration resource for the Terraform Vault Provider. This resource enables management of agent registrations in Vault Enterprise, allowing users to register Vault agents with specific identity entities and configure ceiling policies that limit the maximum permissions an agent can obtain.

Feature Summary

Resource Name: vault_agent_registration
Vault Version Required: 2.0.0+
Vault Edition: Enterprise only
API Endpoints:

• agent-registry/register (create)
• agent-registry/registration/display-name/{name} (read by name, import)
• agent-registry/registration/id/{id} (read/update/delete by ID)

Implementation Details

Files Added

1. internal/vault/sys/agent_registration_resource.go (486 lines)

   • Main resource implementation using Terraform Plugin Framework
   • Implements full CRUD lifecycle (Create, Read, Update, Delete)
   • Includes import functionality
   • Handles namespace support for Vault Enterprise

2. internal/vault/sys/agent_registration_resource_test.go (467 lines)

   • Comprehensive acceptance test suite
   • Tests cover: basic CRUD, import, policies, namespaces, updates
   • 8 test scenarios with multiple test steps each

3. website/docs/r/agent_registration.html.md (186 lines)

   • Complete user-facing documentation
   • Multiple usage examples (basic, with policies, namespaces, etc.)
   • Full argument and attribute reference
   • Import instructions and usage notes

Files Modified

1. internal/consts/consts.go

   • Added 4 new field constants for agent registration:
     • FieldCeilingPolicyIdentifiers
     • FieldNoDefaultCeilingPolicy
     • FieldCreationTime
     • FieldLastUpdatedTime

2. internal/provider/fwprovider/provider.go

   • Registered NewAgentRegistrationResource in the provider's Resources() method

3. CHANGELOG.md

   • Added feature entry under Unreleased > FEATURES section

Resource Schema

Required Fields

• display_name (string) - Unique identifier for the agent, requires replacement on change
• entity_id (string) - ID of the identity entity to associate with the agent

Optional Fields

• namespace (string) - Vault Enterprise namespace
• ceiling_policy_identifiers (list of strings) - Policy names defining maximum permissions
• no_default_ceiling_policy (bool) - Opt out of default ceiling policy (default: false)
• description (string) - Human-readable description

Computed Fields

• id (string) - Resource identifier (same as display_name)
• creation_time (string) - RFC3339 timestamp of creation
• last_updated_time (string) - RFC3339 timestamp of last update

Key Implementation Features

1. Ceiling Policy Management

• Supports multiple ceiling policies per agent
• Automatically filters out default policies when reading state
• Policies define maximum permissions (ceiling) for the agent
• Agent cannot exceed ceiling even if entity/token policies grant more

2. Namespace Support

• Full support for Vault Enterprise namespaces
• Import format: namespace/display_name for namespaced resources
• Import format: display_name for root namespace resources

3. Import Functionality

• Simple import using display name
• Namespace-aware import with custom ID parsing
• Properly reconstructs state from Vault API

4. State Management

• Read-after-write pattern for Create and Update operations
• Proper 404 handling (removes from state)
• Computed fields updated from API responses
• Write-only field handling (none in this resource)

5. Plan Modifiers

• display_name requires replacement (immutable identifier)
• Computed fields use UseStateForUnknown for stability

Test Coverage

Test Scenarios

1. Basic CRUD - Create, read, update, delete with import
2. With Policies - Agent with ceiling policies
3. No Default Policy - Opt out of default ceiling policy
4. With Description - Description field and updates
5. Update Policies - Changing ceiling policies
6. Requires Replace - Verify display_name changes force replacement
7. Namespace - Agent registration in custom namespace
8. Multiple Policies - Agent with multiple ceiling policies

Test Patterns

• Uses resource.Test with multiple steps
• Import verification with custom ID functions
• Proper PreCheck for Enterprise features
• Comprehensive attribute checking
• Dependency management (entities, policies, namespaces)

API Integration

Endpoints Used

• Create: POST agent-registry/register
• Read by Name: GET agent-registry/registration/display-name/{display_name} (used during import)
• Read by ID: GET agent-registry/registration/id/{id} (used after create/update)
• Update: PUT agent-registry/registration/id/{id}
• Delete: DELETE agent-registry/registration/id/{id}

Request/Response Handling

• Uses api.Client.Logical() for all operations
• Proper error handling with context-aware messages
• JSON marshaling/unmarshaling for API models
• Namespace injection via client configuration

Design Decisions

1. Display Name as Identifier

• Chose display_name over auto-generated IDs for user-friendliness
• Makes import intuitive: terraform import vault_agent_registration.example my-agent
• Requires replacement on change (immutable identifier)

2. Policy Filtering

• Default policies automatically filtered from state
• Users only see policies they explicitly configured
• Prevents drift from Vault's automatic default policy application

3. Separate API Model

• AgentRegistrationModel for Terraform state
• AgentRegistrationAPIModel for Vault API
• Clean separation of concerns
• Easier to handle field transformations

4. Framework Choice

• Uses Terraform Plugin Framework (modern approach)
• Type-safe schema definitions
• Better plan modifier support
• Improved diagnostics

Usage Examples

Basic Usage

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
}

With Ceiling Policies

resource "vault_policy" "agent_ceiling" {
  name = "agent-ceiling-policy"
  policy = <<EOT
path "secret/data/*" {
  capabilities = ["read"]
}
EOT
}

resource "vault_agent_registration" "example" {
  display_name               = "my-agent"
  entity_id                  = vault_identity_entity.agent.id
  ceiling_policy_identifiers = [vault_policy.agent_ceiling.name]
}

Best Practices

For Users

1. Always create the identity entity before the agent registration
2. Use descriptive display names for easy identification
3. Configure ceiling policies to limit agent permissions
4. Use descriptions to document agent purpose
5. Consider namespace organization for multi-tenant setups

For Developers

1. Follow TFVP resource development patterns
2. Use read-after-write for consistency
3. Implement comprehensive test coverage
4. Document all fields thoroughly
5. Handle Enterprise features gracefully

Security Considerations

1. Ceiling Policies: Act as a security boundary - agents cannot exceed these permissions
2. Entity Association: Links agent to identity system for audit trails
3. Namespace Isolation: Enterprise namespaces provide tenant isolation
4. No Sensitive Data: Resource doesn't handle passwords or tokens directly

Design Decision: Resource Only (No Data Source)

This implementation includes only the vault_agent_registration resource, not a corresponding data source. This was a deliberate design decision based on the following considerations:

Why No Data Source?

1. Primary Use Case: Agent registrations are primarily created and managed by Terraform, not read from existing registrations. The typical workflow is:

   • Create identity entity
   • Register agent with that entity
   • Configure ceiling policies

2. Import Covers Read Scenarios: The resource's import functionality handles the main "read existing" use case:

   terraform import vault_agent_registration.example my-agent

3. Limited Query Patterns: The Vault API for agent registrations doesn't support list operations or complex queries. You need to know the exact display_name to read an agent registration, which makes a data source less useful than typical data sources that support discovery.

4. State Management: Agent registrations are stateful resources that Terraform should manage. Reading them as data sources could lead to confusion about ownership and lifecycle management.

5. Scope Limitation: This initial implementation focuses on the core management workflow. A data source can be added later if user feedback indicates a strong need.

When a Data Source Might Be Useful

A data source could be valuable in future versions for scenarios like:

• Reading agent registrations created outside Terraform
• Discovering agents in a namespace for reporting
• Referencing agent details in other resources
• Audit and compliance workflows

If these use cases emerge, a data source can be added in a future release without breaking changes.

Future Enhancements

Potential improvements for future versions:

1. Data source for reading agent registrations (if user demand emerges)
2. List data source for discovering all agents in a namespace (if API supports it)
3. Bulk import support for multiple agents
4. Agent status monitoring
5. Integration with agent auto-auth workflows
6. Policy template support

References

• Vault API Documentation: agent-registry/* endpoints
• Terraform Plugin Framework: https://developer.hashicorp.com/terraform/plugin/framework
• TFVP Development Guide: Internal documentation
• Vault Enterprise Features: https://www.vaultproject.io/docs/enterprise

Changelog Entry

* **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+.

Testing Instructions

Prerequisites

• Vault Enterprise 2.0.0 or later
• Valid Vault Enterprise license
• Terraform 1.0+

Running Tests

# Run all agent registration tests
TF_ACC=1 go test ./internal/vault/sys -v -run TestAccAgentRegistration

# Run specific test
TF_ACC=1 go test ./internal/vault/sys -v -run TestAccAgentRegistration_basic

# Run with namespace tests (requires Enterprise)
TF_ACC=1 VAULT_NAMESPACE=root go test ./internal/vault/sys -v -run TestAccAgentRegistration_namespace

Manual Testing

# Initialize Terraform
terraform init

# Plan changes
terraform plan

# Apply configuration
terraform apply

# Import existing agent
terraform import vault_agent_registration.example my-agent

# Verify state
terraform show

Conclusion

This implementation provides a complete, production-ready resource for managing Vault agent registrations. It follows all TFVP best practices, includes comprehensive testing, and provides clear documentation for users. The resource integrates seamlessly with Vault's identity system and policy framework to enable secure, manageable agent deployments.