@robinmordasiewicz/f5xc-terraform-mcp 2.3.0 → 2.4.3

package/dist/docs/functions/blindfold.md

@@ -0,0 +1,133 @@
+---
+page_title: "blindfold function - terraform-provider-f5xc"
+description: |-
+  Encrypts base64-encoded plaintext using F5 Distributed Cloud Secret Management (blindfold).
+  Returns a sealed secret string suitable for use in blindfold_secret_info.location fields.
+  Security: The encryption happens locally using the public key fetched from F5XC.
+  The plaintext secret is never transmitted to F5XC during encryption.
+  Example
+  
+  resource "f5xc_http_loadbalancer" "example" {
+    name = "secure-lb"
+  
+    tls_parameters {
+      private_key {
+        blindfold_secret_info {
+          location = provider::f5xc::blindfold(
+            base64encode(file("${path.module}/private.key")),
+            "example-secret-policy",
+            "shared"
+          )
+        }
+      }
+    }
+  }
+---
+
+# function: blindfold
+
+Encrypts base64-encoded plaintext using F5 Distributed Cloud Secret Management (blindfold).
+
+Returns a sealed secret string suitable for use in `blindfold_secret_info.location` fields.
+
+**Security**: The encryption happens locally using the public key fetched from F5XC.
+The plaintext secret is **never** transmitted to F5XC during encryption.
+
+### Example
+
+```hcl
+resource "f5xc_http_loadbalancer" "example" {
+  name = "secure-lb"
+
+  tls_parameters {
+    private_key {
+      blindfold_secret_info {
+        location = provider::f5xc::blindfold(
+          base64encode(file("${path.module}/private.key")),
+          "example-secret-policy",
+          "shared"
+        )
+      }
+    }
+  }
+}
+```
+
+~> **Note:** This function requires Terraform 1.8 or later.
+
+## Signature
+
+<!-- signature generated by tfplugindocs -->
+```text
+blindfold(plaintext string, policy_name string, namespace string) string
+```
+
+## Arguments
+
+<!-- arguments generated by tfplugindocs -->
+1. `plaintext` (String) Base64-encoded plaintext to encrypt. Use Terraform's `base64encode()` function for raw strings or file contents.
+
+Example: `base64encode(file("private.key"))`
+1. `policy_name` (String) Name of the SecretPolicy that controls which clients can decrypt this secret.
+
+The policy must exist in the specified namespace before encryption.
+1. `namespace` (String) F5XC namespace containing the SecretPolicy.
+
+Common values: `shared`, `system`, or your application namespace.
+
+## Example Usage
+
+```terraform
+# Encrypt a secret string using F5XC blindfold
+#
+# The blindfold function encrypts base64-encoded plaintext using F5 Distributed
+# Cloud Secret Management. The encryption happens locally - your secret is never
+# transmitted to F5XC during encryption.
+
+# Example: Encrypt a password for use in origin pool authentication
+locals {
+  encrypted_password = provider::f5xc::blindfold(
+    base64encode("example-secret-password"),
+    "production-secrets-policy",
+    "shared"
+  )
+}
+
+# Example: Encrypt a TLS private key from a file
+locals {
+  encrypted_key = provider::f5xc::blindfold(
+    base64encode(file("${path.module}/certs/private.key")),
+    "tls-secrets-policy",
+    "shared"
+  )
+}
+
+# Example: Using the encrypted secret in a resource
+resource "f5xc_http_loadbalancer" "example" {
+  name      = "secure-lb"
+  namespace = "production"
+
+  domains = ["example.com"]
+
+  https_auto_cert {
+    tls_config {
+      custom_security {
+        private_key {
+          blindfold_secret_info {
+            location = provider::f5xc::blindfold(
+              base64encode(file("${path.module}/certs/server.key")),
+              "tls-secrets-policy",
+              "shared"
+            )
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+
+## See Also
+
+- [F5XC Secret Management Documentation](https://docs.cloud.f5.com/docs/how-to/advanced-security/blindfold-your-tls-certificates)

package/dist/docs/functions/blindfold_file.md

@@ -0,0 +1,154 @@
+---
+page_title: "blindfold_file function - terraform-provider-f5xc"
+description: |-
+  Reads a file and encrypts its contents using F5 Distributed Cloud Secret Management (blindfold).
+  Returns a sealed secret string suitable for use in blindfold_secret_info.location fields.
+  This is a convenience function equivalent to:
+  
+  provider::f5xc::blindfold(base64encode(file(path)), policy_name, namespace)
+  
+  Security: The encryption happens locally using the public key fetched from F5XC.
+  The file contents are never transmitted to F5XC during encryption.
+  Example
+  
+  resource "f5xc_http_loadbalancer" "example" {
+    name = "secure-lb"
+  
+    tls_parameters {
+      private_key {
+        blindfold_secret_info {
+          location = provider::f5xc::blindfold_file(
+            "${path.module}/certs/private.key",
+            "example-secret-policy",
+            "shared"
+          )
+        }
+      }
+    }
+  }
+---
+
+# function: blindfold_file
+
+Reads a file and encrypts its contents using F5 Distributed Cloud Secret Management (blindfold).
+
+Returns a sealed secret string suitable for use in `blindfold_secret_info.location` fields.
+
+This is a convenience function equivalent to:
+```hcl
+provider::f5xc::blindfold(base64encode(file(path)), policy_name, namespace)
+```
+
+**Security**: The encryption happens locally using the public key fetched from F5XC.
+The file contents are **never** transmitted to F5XC during encryption.
+
+### Example
+
+```hcl
+resource "f5xc_http_loadbalancer" "example" {
+  name = "secure-lb"
+
+  tls_parameters {
+    private_key {
+      blindfold_secret_info {
+        location = provider::f5xc::blindfold_file(
+          "${path.module}/certs/private.key",
+          "example-secret-policy",
+          "shared"
+        )
+      }
+    }
+  }
+}
+```
+
+~> **Note:** This function requires Terraform 1.8 or later.
+
+## Signature
+
+<!-- signature generated by tfplugindocs -->
+```text
+blindfold_file(path string, policy_name string, namespace string) string
+```
+
+## Arguments
+
+<!-- arguments generated by tfplugindocs -->
+1. `path` (String) Path to the file to encrypt. Can be absolute or relative to the Terraform working directory.
+
+Use `${path.module}` for paths relative to the current module.
+1. `policy_name` (String) Name of the SecretPolicy that controls which clients can decrypt this secret.
+
+The policy must exist in the specified namespace before encryption.
+1. `namespace` (String) F5XC namespace containing the SecretPolicy.
+
+Common values: `shared`, `system`, or your application namespace.
+
+## Example Usage
+
+```terraform
+# Encrypt a file using F5XC blindfold
+#
+# The blindfold_file function reads a file and encrypts its contents using F5
+# Distributed Cloud Secret Management. This is a convenience function equivalent
+# to: provider::f5xc::blindfold(base64encode(file(path)), policy_name, namespace)
+#
+# The encryption happens locally - file contents are never transmitted to F5XC.
+
+# Example: Encrypt a TLS private key file
+resource "f5xc_http_loadbalancer" "secure" {
+  name      = "secure-lb"
+  namespace = "production"
+
+  domains = ["secure.example.com"]
+
+  https_auto_cert {
+    tls_config {
+      custom_security {
+        private_key {
+          blindfold_secret_info {
+            location = provider::f5xc::blindfold_file(
+              "${path.module}/certs/server.key",
+              "tls-secrets-policy",
+              "shared"
+            )
+          }
+        }
+        certificate {
+          certificate_url = "string:///${base64encode(file("${path.module}/certs/server.crt"))}"
+        }
+      }
+    }
+  }
+}
+
+# Example: Encrypt multiple certificate files using for_each
+locals {
+  certificates = {
+    "server"  = "${path.module}/certs/server.key"
+    "client"  = "${path.module}/certs/client.key"
+    "ca"      = "${path.module}/certs/ca.key"
+  }
+}
+
+resource "f5xc_certificate" "certs" {
+  for_each  = local.certificates
+  name      = each.key
+  namespace = "production"
+
+  private_key {
+    blindfold_secret_info {
+      location = provider::f5xc::blindfold_file(
+        each.value,
+        "cert-secrets-policy",
+        "shared"
+      )
+    }
+  }
+}
+```
+
+
+## See Also
+
+- [F5XC Secret Management Documentation](https://docs.cloud.f5.com/docs/how-to/advanced-security/blindfold-your-tls-certificates)

package/dist/docs/guides/authentication.md

@@ -0,0 +1,389 @@
+---
+page_title: "Guide: Authentication Methods"
+subcategory: "Guides"
+description: |-
+  Comprehensive guide to authenticating the F5 Distributed Cloud Terraform
+  provider using API tokens, P12 certificates, or PEM certificates.
+---
+
+# Authentication Methods
+
+This guide covers authentication configuration for the F5 Distributed Cloud Terraform provider.
+
+## Quick Reference
+
+| Method | Complexity | Best For | Security |
+|--------|------------|----------|----------|
+| API Token | Simplest | Development, quick testing | Bearer token over TLS |
+| P12 Certificate | Moderate | Production, CI/CD | Mutual TLS (mTLS) |
+| PEM Certificate | Advanced | When tooling requires PEM format | Derived from P12, mTLS |
+
+## Prerequisites
+
+- **F5 Distributed Cloud Account** - Sign up at <https://www.f5.com/cloud/products/distributed-cloud-console>
+- **Terraform >= 1.8** - Download from <https://www.terraform.io/downloads>
+- **Console Access** - Ability to create credentials in the F5XC Console
+
+## Creating Credentials in F5 Distributed Cloud
+
+### Personal Credentials
+
+Personal credentials are tied to your user account and ideal for development.
+
+#### Creating an API Token
+
+1. Open the F5 Distributed Cloud Console
+2. Navigate to **Administration** → **Personal Management** → **Credentials**
+3. Click **+ Add Credentials**
+4. Enter a name (e.g., "terraform-dev-token")
+5. Select **API Token** from the dropdown
+6. Choose an expiry date
+7. Click **Generate**, then **Copy** the token value
+
+!> **Warning:** Copy and save your token immediately. You cannot retrieve it after closing this dialog.
+
+#### Creating a P12 Certificate
+
+1. Navigate to **Administration** → **Personal Management** → **Credentials**
+2. Click **+ Add Credentials**
+3. Enter a name (e.g., "terraform-dev-cert")
+4. Select **API Certificate** from the dropdown
+5. Enter and confirm a password
+6. Select an expiry date
+7. Click **Download** to get the `.p12` file
+
+-> **Tip:** Store the P12 file securely and never commit it to version control.
+
+### Service Credentials (IAM)
+
+Service credentials are managed through IAM and recommended for production. They can be scoped to specific roles and namespaces.
+
+#### Creating a Service API Token
+
+1. Navigate to **Administration** → **IAM** → **Service Credentials**
+2. Click **+ Add Service Credentials**
+3. Enter a name (e.g., "terraform-cicd-token")
+4. Select **API Token** from the dropdown
+5. Optionally assign roles and namespaces to limit scope
+6. Choose an expiry date
+7. Click **Generate**, then **Copy** the token value
+
+#### Creating a Service P12 Certificate
+
+1. Navigate to **Administration** → **IAM** → **Service Credentials**
+2. Click **+ Add Service Credentials**
+3. Enter a name
+4. Select **API Certificate** from the dropdown
+5. Optionally assign roles and namespaces
+6. Enter and confirm a password
+7. Select an expiry date
+8. Click **Download** to get the `.p12` file
+
+## Authentication Methods
+
+### Method 1: API Token Authentication (Simplest)
+
+API tokens provide bearer token authentication over TLS. This is the quickest way to get started.
+
+**Using Environment Variables:**
+
+```bash
+export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
+export F5XC_API_TOKEN="your-api-token"
+```
+
+**Using Provider Configuration:**
+
+```hcl
+provider "f5xc" {
+  api_url   = var.f5xc_api_url
+  api_token = var.f5xc_api_token
+}
+```
+
+### Method 2: P12 Certificate Authentication (Recommended for Production)
+
+P12 certificates provide mutual TLS (mTLS) authentication, where both client and server verify each other's identity.
+
+**Using Environment Variables:**
+
+```bash
+export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
+export F5XC_P12_FILE="/path/to/your-credentials.p12"
+export F5XC_P12_PASSWORD="your-p12-password"  # pragma: allowlist secret
+```
+
+**Using Provider Configuration:**
+
+```hcl
+provider "f5xc" {
+  api_url      = var.f5xc_api_url
+  api_p12_file = var.f5xc_api_p12_file
+  p12_password = var.f5xc_p12_password
+}
+```
+
+### Method 3: PEM Certificate Authentication (Derived from P12)
+
+PEM authentication uses separate certificate and private key files. Since F5XC only provides P12 certificates, you must extract PEM files using OpenSSL.
+
+**When to use this method:** Only when your tooling specifically requires PEM format instead of P12.
+
+**Step 1: Extract PEM files from P12:**
+
+```bash
+# Create a directory for certificates
+mkdir -p certs
+
+# Extract the certificate
+openssl pkcs12 -in ~/your-tenant.console.ves.volterra.io.api-creds.p12 \
+  -nodes -nokeys -out certs/f5xc.cert
+# Enter Import Password: <your p12 password>
+
+# Extract the private key
+openssl pkcs12 -in ~/your-tenant.console.ves.volterra.io.api-creds.p12 \
+  -nodes -nocerts -out certs/f5xc.key
+# Enter Import Password: <your p12 password>
+```
+
+**Step 2: Configure the provider:**
+
+**Using Environment Variables:**
+
+```bash
+export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
+export F5XC_CERT="/path/to/certs/f5xc.cert"
+export F5XC_KEY="/path/to/certs/f5xc.key"
+```
+
+**Using Provider Configuration:**
+
+```hcl
+provider "f5xc" {
+  api_url  = var.f5xc_api_url
+  api_cert = var.f5xc_api_cert
+  api_key  = var.f5xc_api_key
+}
+```
+
+~> **Note:** For server certificate verification, specify a CA certificate using `F5XC_CACERT` environment variable or `api_ca_cert` provider attribute.
+
+## Environment Variable Reference
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `F5XC_API_URL` | F5XC tenant API URL | Yes |
+| `F5XC_API_TOKEN` | API token for bearer authentication | One of: token, P12, or PEM |
+| `F5XC_P12_FILE` | Path to P12 certificate file | With `F5XC_P12_PASSWORD` |
+| `F5XC_P12_PASSWORD` | Password for P12 file | With `F5XC_P12_FILE` |
+| `F5XC_CERT` | Path to PEM certificate file | With `F5XC_KEY` |
+| `F5XC_KEY` | Path to PEM private key file | With `F5XC_CERT` |
+| `F5XC_CACERT` | Path to CA certificate for server verification | No |
+
+**Adding to Shell Profile:**
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export F5XC_API_URL="https://your-tenant.console.ves.volterra.io"
+export F5XC_API_TOKEN="your-api-token"
+```
+
+Then reload: `source ~/.zshrc` or `source ~/.bashrc`
+
+### Authentication Priority
+
+When multiple methods are configured, the provider uses this priority:
+
+1. **P12 Certificate** - If `api_p12_file` is set (requires `p12_password`)
+2. **PEM Certificate** - If both `api_cert` and `api_key` are set
+3. **API Token** - If `api_token` is set
+4. **Error** - If none are provided
+
+## CI/CD Integration
+
+### GitHub Actions with API Token
+
+```yaml
+name: Terraform Deploy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  terraform:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "1.8.0"
+
+      - name: Terraform Init
+        run: terraform init
+
+      - name: Terraform Plan
+        env:
+          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
+          F5XC_API_TOKEN: ${{ secrets.F5XC_API_TOKEN }}
+        run: terraform plan -out=tfplan
+
+      - name: Terraform Apply
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        env:
+          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
+          F5XC_API_TOKEN: ${{ secrets.F5XC_API_TOKEN }}
+        run: terraform apply -auto-approve tfplan
+```
+
+**GitHub Secrets to configure:**
+
+| Secret Name | Value |
+|-------------|-------|
+| `F5XC_API_URL` | `https://your-tenant.console.ves.volterra.io` |
+| `F5XC_API_TOKEN` | Your API token value |
+
+### GitHub Actions with P12 Certificate
+
+For production deployments requiring mTLS:
+
+```yaml
+name: Terraform Deploy with P12
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  terraform:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "1.8.0"
+
+      - name: Setup P12 Certificate
+        run: |
+          echo "${{ secrets.F5XC_P12_BASE64 }}" | base64 -d > /tmp/f5xc-credentials.p12
+          chmod 600 /tmp/f5xc-credentials.p12
+
+      - name: Terraform Init
+        run: terraform init
+
+      - name: Terraform Plan
+        env:
+          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
+          F5XC_P12_FILE: /tmp/f5xc-credentials.p12
+          F5XC_P12_PASSWORD: ${{ secrets.F5XC_P12_PASSWORD }}
+        run: terraform plan -out=tfplan
+
+      - name: Terraform Apply
+        env:
+          F5XC_API_URL: ${{ secrets.F5XC_API_URL }}
+          F5XC_P12_FILE: /tmp/f5xc-credentials.p12
+          F5XC_P12_PASSWORD: ${{ secrets.F5XC_P12_PASSWORD }}
+        run: terraform apply -auto-approve tfplan
+
+      - name: Cleanup
+        if: always()
+        run: rm -f /tmp/f5xc-credentials.p12
+```
+
+**Encoding P12 for GitHub Secrets:**
+
+```bash
+# On macOS
+base64 -i your-credentials.p12 | pbcopy
+
+# On Linux
+base64 -w 0 your-credentials.p12
+```
+
+**GitHub Secrets to configure:**
+
+| Secret Name | Value |
+|-------------|-------|
+| `F5XC_API_URL` | `https://your-tenant.console.ves.volterra.io` |
+| `F5XC_P12_BASE64` | Base64-encoded P12 file contents |
+| `F5XC_P12_PASSWORD` | Password for the P12 file |
+
+## Security Best Practices
+
+- **Never commit credentials** to version control. Add `*.tfvars`, `*.p12`, and `*.pem` to `.gitignore`
+- **Use environment variables** for sensitive values in local development
+- **Use GitHub Secrets** or equivalent for CI/CD pipelines
+- **Limit credential scope** using Service Credentials with specific roles and namespaces
+
+### Choosing the Right Method
+
+| Use Case | Recommended Method | Reason |
+|----------|-------------------|--------|
+| Local development | API Token | Simplest setup |
+| CI/CD pipelines | P12 Certificate | mTLS security |
+| Production automation | Service Credentials | Role-based access control |
+
+## Troubleshooting
+
+### Authentication Failed (401 Unauthorized)
+
+1. Verify API URL does **NOT** include `/api` suffix (e.g., `https://tenant.console.ves.volterra.io`)
+2. Check token hasn't expired
+3. Verify token copied correctly (no whitespace)
+4. Ensure environment variables are exported:
+
+```bash
+echo $F5XC_API_URL
+echo $F5XC_API_TOKEN
+```
+
+### Certificate Verification Failed
+
+1. Verify P12 password is correct
+2. Check file path is absolute or correctly relative
+3. Test P12 file:
+
+```bash
+openssl pkcs12 -in your-credentials.p12 -nokeys -info
+```
+
+### Permission Denied (403 Forbidden)
+
+1. Verify credential has required permissions
+2. For Service Credentials, check role and namespace assignments
+3. Some operations require specific system roles
+
+### Environment Variables Not Working
+
+1. Ensure variables are exported:
+
+```bash
+export F5XC_API_TOKEN="token"  # Correct
+F5XC_API_TOKEN="token"         # Won't work
+```
+
+2. Verify spelling is exact (case-sensitive)
+3. Check for hidden characters in values
+
+## Revoking Credentials
+
+1. Navigate to **Administration** → **Personal Management** → **Credentials** (or **IAM** → **Service Credentials**)
+2. Find the credential
+3. Click **Actions** (three dots) → **Force Expiry**
+
+## Next Steps
+
+- [HTTP Load Balancer Guide](http-loadbalancer) - Deploy your first load balancer
+- [Blindfold Functions Guide](blindfold) - Secure secret management
+- [Namespace Resource](../resources/namespace) - Organize your resources
+
+## Support
+
+- [Provider Documentation](../index)
+- [F5 Distributed Cloud Docs](https://docs.cloud.f5.com/)
+- [F5 Credentials Guide](https://docs.cloud.f5.com/docs-v2/administration/how-tos/user-mgmt/Credentials)
+- [GitHub Issues](https://github.com/robinmordasiewicz/terraform-provider-f5xc/issues)