feat(skills): add secrets-1password-dev skill
- 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
Assessment
This issue has not been assessed yet.