aRustyDev / aRustyDev/agents

feat(skills): add secrets-1password-dev skill

Open
#815 0 comments 0 reactions 1 assignee Claimed by @aRustyDev View on GitHub
Dominant language
Jupyter Notebook
Stars
8
Forks
3
PR merge metrics
No merged PRs in 30d

Description

## Summary

Create a new skill `secrets-1password-dev` for 1Password integration patterns across multiple tools and platforms, including comprehensive comparisons with alternative solutions.

## Context & Motivation

This skill gap was identified during a homelab Kubernetes deployment where 1Password was used as the secrets backend. Multiple integration points were required:
- Ansible roles retrieving secrets via `op` CLI
- Kubernetes external-secrets operator syncing from 1Password
- Shell scripts for bootstrap operations
- Potential future integrations (Terraform, application code)

### The Triggering Incidents

Several bugs and configuration issues arose from 1Password integration:

1. **Document vs Item Confusion**
- 1Password has both "documents" (file attachments) and "items" (structured data)
- `op document get` vs `op item get` have different behavior
- API_CREDENTIAL items require specific field access patterns
- Incorrect retrieval method led to malformed secrets

2. **ClusterSecretStore Vault Name Case Sensitivity**
- 1Password vault names are case-sensitive
- "homelab" ≠ "Homelab"
- Resulted in "vault not found" errors

3. **Memory Requirements for 1Password SDK**
- external-secrets 1Password provider uses the full SDK
- Requires significantly more memory than other providers
- Default 128Mi limit caused OOMKilled
- Required 512Mi for stable operation

4. **Base64 Encoding Handling**
- Different tools handle base64 encoding differently
- Ansible `slurp` auto-encodes, requiring decode
- 1Password stores some values pre-encoded
- Kubernetes secrets are base64 encoded
- Easy to double-encode or forget to encode

## Use Cases

This skill should support:

1. **CLI Integration (`op` command)**
- Authentication patterns (service accounts, user accounts)
- Document retrieval vs item retrieval
- Field access for different item types
- Batch operations and scripting
- Environment variable injection

2. **Ansible Integration**
- Reusable role for secret retrieval
- Handling different secret types (files, credentials, API keys)
- Error handling and validation
- Caching considerations

3. **Kubernetes Integration (external-secrets)**
- ClusterSecretStore configuration
- 1Password Connect vs SDK provider
- Resource requirements (memory, CPU)
- Secret refresh and rotation
- Templating and transformation

4. **Terraform Integration**
- 1Password provider configuration
- Data sources for secrets
- Handling sensitive outputs
- State file security considerations

5. **Application Integration**
- Rust SDK usage patterns
- Python SDK usage patterns
- Go SDK usage patterns
- Connect server vs direct SDK

6. **Shell Script Integration**
- Bootstrap scripts using `op`
- Service account authentication
- Secure output handling
- Error handling patterns

## Key Requirements

### Must Include

1. **1Password Concepts Reference**
- Vaults, Items, Documents, Fields
- Item types (Login, API_CREDENTIAL, Secure Note, Document, etc.)
- Access patterns for each type
- Case sensitivity gotchas

2. **CLI Reference (`op`)**
- Authentication methods
- Common commands with examples
- Field reference syntax
- Environment variables
- Service account setup

3. **Integration Patterns by Tool**

| Tool | Integration Method | Key Considerations |
|------|-------------------|-------------------|
| Ansible | `op` CLI via command/shell | Escape handling, fact management |
| Terraform | hashicorp/onepassword provider | State sensitivity, data sources |
| external-secrets | 1Password provider | Memory requirements, Connect vs SDK |
| Shell | `op` CLI direct | Service accounts, secure output |
| Rust | 1password crate | Async patterns, error handling |
| Python | onepassword SDK | Connect client setup |
| Go | 1password SDK | Context handling |

4. **Comparison with Alternatives**

| Solution | Pros | Cons | Best For |
|----------|------|------|----------|
| 1Password | User-friendly, multi-platform | Cost, SDK complexity | Teams already using 1Password |
| HashiCorp Vault | Feature-rich, OSS | Operational complexity | Large-scale enterprise |
| AWS Secrets Manager | Native AWS integration | AWS lock-in | AWS-centric workloads |
| SOPS | Git-friendly, simple | Limited features | GitOps workflows |
| Sealed Secrets | K8s-native | K8s only | Pure Kubernetes |
| Doppler | Developer-friendly | SaaS dependency | App configuration |

5. **ADRs (Architecture Decision Records)**
- Why 1Password over Vault for homelab
- SDK provider vs Connect server for external-secrets
- Service account vs user account for automation
- Secret organization (vault structure, naming conventions)

6. **Troubleshooting Guide**
- Authentication failures
- Vault/item not found
- Memory issues with SDK
- Rate limiting
- Encoding problems

### Templates to Include

- Ansible role for 1Password secret retrieval
- ClusterSecretStore YAML template
- Terraform provider configuration
- Shell script bootstrap pattern
- ExternalSecret templates for common patterns

### References to Include

- 1Password CLI documentation
- 1Password Connect documentation
- 1Password SDK documentation (Rust, Python, Go)
- external-secrets 1Password provider docs
- Terraform 1Password provider docs
- HashiCorp Vault documentation (for comparison)

### Comparison Documents

Include detailed comparison docs for:
- 1Password vs HashiCorp Vault
- 1Password vs cloud-native solutions (AWS SM, GCP SM, Azure KV)
- 1Password vs GitOps solutions (SOPS, Sealed Secrets)
- Connect server vs SDK provider (external-secrets)

## Related Issues

- Part of skill gap detection from homelab K8s deployment session
- Related to #813 (iac-ansible-roles-dev) and #814 (homelab-k8s-ops)
- Complements existing `openmetadata-*` skills that may need secrets integration

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.