terraform-provider-edge-connect/examples/ENV_VARS.md

# Environment Variables Reference

This document provides a complete reference for all environment variables supported by the Edge Connect Terraform provider.

## Supported Environment Variables

| Variable | Type | Required | Description |
|----------|------|----------|-------------|
| `EDGE_CONNECT_ENDPOINT` | string | Yes | The Edge Connect API endpoint URL |
| `EDGE_CONNECT_TOKEN` | string | Conditional* | API token for authentication |
| `EDGE_CONNECT_USERNAME` | string | Conditional* | Username for authentication |
| `EDGE_CONNECT_PASSWORD` | string | Conditional* | Password for authentication |

\* Either `EDGE_CONNECT_TOKEN` OR both `EDGE_CONNECT_USERNAME` and `EDGE_CONNECT_PASSWORD` must be provided.

## Quick Start

### Token Authentication

```bash
export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_TOKEN="your-api-token-here"

terraform init
terraform plan
terraform apply
```

### Username/Password Authentication

```bash
export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_USERNAME="your-username"
export EDGE_CONNECT_PASSWORD="your-password"

terraform init
terraform plan
terraform apply
```

## Configuration Precedence

The provider reads configuration in the following order (highest to lowest precedence):

1. **Explicit Configuration** - Values set directly in the provider block
2. **Environment Variables** - Values from environment variables
3. **Default Values** - Provider defaults (if any)

### Example: Precedence in Action

```hcl
provider "edge-connect" {
  endpoint = "https://api.example.com"  # This value is used
  # token will be read from EDGE_CONNECT_TOKEN environment variable
}
```

If `EDGE_CONNECT_TOKEN` is set in the environment, it will be used for the token even though it's not specified in the configuration.

## Usage Patterns

### 1. Pure Environment Variable Configuration

No explicit configuration needed in Terraform files:

```hcl
provider "edge-connect" {}
```

All configuration comes from environment variables.

### 2. Mixed Configuration

Some values explicit, others from environment:

```hcl
provider "edge-connect" {
  endpoint = "https://api.edge-connect.example.com"
  # token, username, and password from environment variables
}
```

### 3. Override Environment Variables

Explicit configuration overrides environment variables:

```hcl
provider "edge-connect" {
  endpoint = "https://api.edge-connect.example.com"
  token    = var.edge_connect_token  # Overrides EDGE_CONNECT_TOKEN
}
```

## Shell Integration

### Bash/Zsh Profile

Add to `~/.bashrc` or `~/.zshrc`:

```bash
# Edge Connect API Configuration
export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_TOKEN="your-token"
```

### direnv (Recommended)

Create a `.envrc` file in your project directory:

```bash
# .envrc
export EDGE_CONNECT_ENDPOINT="https://api.edge-connect.example.com"
export EDGE_CONNECT_TOKEN="your-token"
```

Enable direnv:
```bash
direnv allow
```

Now environment variables are automatically loaded when you enter the directory.

### CI/CD Systems

#### GitHub Actions

```yaml
- name: Terraform Apply
  env:
    EDGE_CONNECT_ENDPOINT: ${{ secrets.EDGE_CONNECT_ENDPOINT }}
    EDGE_CONNECT_TOKEN: ${{ secrets.EDGE_CONNECT_TOKEN }}
  run: |
    terraform init
    terraform apply -auto-approve
```

#### GitLab CI

```yaml
terraform:
  script:
    - terraform init
    - terraform apply -auto-approve
  variables:
    EDGE_CONNECT_ENDPOINT: $EDGE_CONNECT_ENDPOINT
    EDGE_CONNECT_TOKEN: $EDGE_CONNECT_TOKEN
```

#### Jenkins

```groovy
withEnv([
  "EDGE_CONNECT_ENDPOINT=https://api.edge-connect.example.com",
  "EDGE_CONNECT_TOKEN=${env.EDGE_CONNECT_TOKEN}"
]) {
  sh 'terraform init'
  sh 'terraform apply -auto-approve'
}
```

## Secret Management Integration

### AWS Secrets Manager

```bash
export EDGE_CONNECT_TOKEN=$(aws secretsmanager get-secret-value \
  --secret-id edge-connect/token \
  --query SecretString \
  --output text)
```

### HashiCorp Vault

```bash
export EDGE_CONNECT_TOKEN=$(vault kv get -field=token secret/edge-connect)
```

### Azure Key Vault

```bash
export EDGE_CONNECT_TOKEN=$(az keyvault secret show \
  --name edge-connect-token \
  --vault-name my-vault \
  --query value -o tsv)
```

### Google Secret Manager

```bash
export EDGE_CONNECT_TOKEN=$(gcloud secrets versions access latest \
  --secret="edge-connect-token")
```

## Security Best Practices

1. **Never commit credentials to version control**
   - Use `.gitignore` for files containing secrets
   - Use environment variables or secret management systems

2. **Use appropriate permissions**
   - Restrict access to environment files
   - Use IAM roles and policies in cloud environments

3. **Rotate credentials regularly**
   - Update environment variables when rotating tokens
   - Use automated rotation with secret management systems

4. **Use token authentication in production**
   - More secure than username/password
   - Easier to rotate and scope

5. **Audit credential usage**
   - Log when credentials are accessed
   - Monitor for unauthorized usage

## Troubleshooting

### Check if environment variables are set:

```bash
env | grep EDGE_CONNECT
```

### Verify values (mask sensitive data):

```bash
echo "Endpoint: $EDGE_CONNECT_ENDPOINT"
echo "Token: ${EDGE_CONNECT_TOKEN:0:5}..." # Show only first 5 chars
```

### Clear environment variables:

```bash
unset EDGE_CONNECT_ENDPOINT
unset EDGE_CONNECT_TOKEN
unset EDGE_CONNECT_USERNAME
unset EDGE_CONNECT_PASSWORD
```

### Common Issues

**Problem:** Provider can't find credentials

**Solution:** Verify environment variables are set in the current shell:
```bash
env | grep EDGE_CONNECT
```

**Problem:** Wrong credentials being used

**Solution:** Check for explicit configuration overriding environment variables, or verify the correct environment variables are set.

## Examples

See the [authentication/](authentication/) directory for complete examples:

- `env-vars.tf` - Pure environment variable configuration
- `env-vars-token.sh` - Shell script for token authentication
- `env-vars-userpass.sh` - Shell script for username/password authentication

## Additional Resources

- [Authentication Examples](authentication/README.md) - Detailed authentication documentation
- [Provider Configuration](README.md) - Main examples README