Skip to content

Commit 4b3a5f0

Browse files
FlorianPeruckiFlorianPerucki
authored
Merge pull request #41 from GitGuardian/fperucki/NHI-699
docs: add k8s authentication method example for hashicorp
2 parents 0e546ab + 32b22c4 commit 4b3a5f0

File tree

6 files changed

+283
-0
lines changed

6 files changed

+283
-0
lines changed

‎charts/ggscout/examples/conjurcloud-workload/README.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Conjur Cloud with Workload Authentication
2+
3+
This example demonstrates how to configure ggscout to authenticate with Conjur Cloud using Workload authentication.
4+
5+
## Prerequisites
6+
7+
1. Access to a Conjur Cloud instance
8+
2. A Conjur workload with appropriate permissions
9+
3. Workload login ID and API key
10+
11+
## Configuration
12+
13+
### 1. Workload Setup
14+
15+
In your Conjur Cloud instance, ensure you have:
16+
- A workload identity configured
17+
- Appropriate policies granting the workload access to secrets
18+
- The workload login ID and API key
19+
20+
### 2. Update Configuration
21+
22+
Edit the `secret.yaml` file to match your environment:
23+
24+
- `CONJUR_WORKLOAD_LOGIN`: Your Conjur workload login ID (e.g., "host/my-app")
25+
- `CONJUR_WORKLOAD_API_KEY`: Your Conjur workload API key
26+
- `CONJUR_SUBDOMAIN`: Your Conjur Cloud subdomain
27+
- `GITGUARDIAN_API_KEY`: Your GitGuardian API token
28+
29+
Edit the `values.yaml` file:
30+
31+
- Update the GitGuardian endpoint URL if needed
32+
- Adjust the fetch and sync schedules as required
33+
34+
### 3. Deploy with Helm
35+
36+
```bash
37+
# Add the ggscout Helm repository
38+
helm repo add ggscout https://gitguardian.github.io/nhi-scout-helm-charts
39+
helm repo update
40+
41+
# Apply the secret first
42+
kubectl apply -f secret.yaml
43+
44+
# Install ggscout with Conjur Cloud Workload authentication
45+
helm install ggscout-conjur ggscout/ggscout -f values.yaml
46+
```
47+
48+
## Verification
49+
50+
Check that ggscout can authenticate with Conjur Cloud:
51+
52+
```bash
53+
# Check the logs of the ggscout pods
54+
kubectl logs -l app.kubernetes.io/name=ggscout
55+
56+
# Check if the CronJobs are running
57+
kubectl get cronjobs
58+
```
59+
60+
## Troubleshooting
61+
62+
1. **Authentication Issues**: Verify the workload login ID and API key are correct
63+
2. **Permission Issues**: Ensure the workload has proper policies to access the required secrets
64+
3. **Network Connectivity**: Verify ggscout pods can reach your Conjur Cloud instance
65+
66+
For more details on Conjur Cloud workload authentication, refer to the [Conjur Cloud documentation](https://docs.cyberark.com/conjur-cloud/).

‎charts/ggscout/examples/conjurcloud-workload/secret.yaml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
apiVersion: v1
3+
kind: Secret
4+
metadata:
5+
name: ggscout-secrets
6+
stringData:
7+
# Conjur Workload authentication
8+
CONJUR_WORKLOAD_LOGIN: "your-workload-login"
9+
CONJUR_WORKLOAD_API_KEY: "your-workload-api-key"
10+
11+
# Conjur subdomain
12+
CONJUR_SUBDOMAIN: "your-conjur-subdomain"
13+
14+
# GitGuardian API token
15+
GITGUARDIAN_API_KEY: "your_gitguardian_token"

‎charts/ggscout/examples/conjurcloud-workload/values.yaml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
# yaml-language-server: $schema=../../values.schema.json
3+
4+
inventory:
5+
config:
6+
sources:
7+
conjur_cloud:
8+
type: conjurcloud
9+
auth_mode: "workload"
10+
login: "${CONJUR_WORKLOAD_LOGIN}"
11+
api_key: "${CONJUR_WORKLOAD_API_KEY}"
12+
fetch_all_versions: true
13+
mode: "read/write" # Can be `read`, `write` or `read/write` depending on wether fetch and/or sync are enabled
14+
subdomain: "${CONJUR_SUBDOMAIN}"
15+
16+
gitguardian:
17+
endpoint: "https://api.gitguardian.com/v1"
18+
api_token: "${GITGUARDIAN_API_KEY}"
19+
jobs:
20+
# Job to fetch defined sources
21+
fetch:
22+
# Set to `false` to disable the job
23+
enabled: true
24+
# Run every 15 minutes
25+
schedule: '*/15 * * * *'
26+
send: true
27+
# Job to be able to sync/write secrets from GitGuardian into you vault
28+
sync:
29+
# Set to `false` to disable the job
30+
enabled: true
31+
# Run every minute
32+
schedule: '* * * * *'
33+
34+
envFrom:
35+
- secretRef:
36+
name: ggscout-secrets

‎charts/ggscout/examples/hashicorpvault-k8s/README.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# HashiCorp Vault with Kubernetes Authentication
2+
3+
This example demonstrates how to configure ggscout to authenticate with HashiCorp Vault using Kubernetes authentication when running in a Kubernetes cluster.
4+
5+
## Prerequisites
6+
7+
1. HashiCorp Vault with Kubernetes auth method enabled
8+
2. Proper Vault policies and roles configured
9+
3. ggscout deployed in a Kubernetes cluster
10+
11+
## Vault Configuration
12+
13+
### 1. Enable Kubernetes Auth Method
14+
15+
```bash
16+
# Enable Kubernetes auth method
17+
vault auth enable kubernetes
18+
```
19+
20+
See HashiCorp Vault reference [documentation](https://developer.hashicorp.com/vault/docs/auth/kubernetes#configuration)
21+
22+
### 2. Configure Kubernetes Auth Method
23+
24+
```bash
25+
# Configure the Kubernetes auth method
26+
vault write auth/kubernetes/config \
27+
token_reviewer_jwt="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" \
28+
kubernetes_host="https://$KUBERNETES_PORT_443_TCP_ADDR:443" \
29+
kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
30+
```
31+
32+
### 3. Create Vault Policy
33+
34+
```bash
35+
# Create policy for ggscout
36+
vault policy write ggscout-policy - <<EOF
37+
# Allow reading secrets from KV2 engine
38+
path "secret/data/*" {
39+
capabilities = ["read", "list"]
40+
}
41+
42+
path "secret/metadata/*" {
43+
capabilities = ["read", "list"]
44+
}
45+
46+
# Allow reading from KV1 engine (if used)
47+
path "secret/*" {
48+
capabilities = ["read", "list"]
49+
}
50+
EOF
51+
```
52+
53+
### 4. Create Vault Kubernetes Role
54+
55+
```bash
56+
# Create Kubernetes auth role
57+
vault write auth/kubernetes/role/ggscout \
58+
bound_service_account_names=ggscout \
59+
policies=ggscout-policy \
60+
ttl=24h
61+
```
62+
63+
## Deployment
64+
65+
### 1. Update Configuration
66+
67+
Edit the `secret.yaml` file to match your environment:
68+
69+
- `VAULT_K8S_ROLE`: The Vault role created above
70+
- `GITGUARDIAN_API_KEY`: Your GitGuardian API token
71+
72+
Edit the `values.yaml` file:
73+
74+
- `vault_address`: Your Vault server URL
75+
- `path`: The Vault path to collect secrets from
76+
- `gitguardian.endpoint`: Your GitGuardian instance URL
77+
- `auth.k8s.service_account`: (Optional) Custom service account name
78+
- `auth.k8s.namespace`: (Optional) Kubernetes namespace for the service account
79+
80+
### 2. Deploy with Helm
81+
82+
```bash
83+
# Add the ggscout Helm repository
84+
helm repo add ggscout https://gitguardian.github.io/nhi-scout-helm-charts
85+
helm repo update
86+
87+
# Apply the secret first
88+
kubectl apply -f secret.yaml
89+
90+
# Install ggscout with Kubernetes authentication
91+
helm install ggscout-vault ggscout/ggscout -f values.yaml
92+
```
93+
94+
## Verification
95+
96+
Check that ggscout can authenticate with Vault:
97+
98+
```bash
99+
# Check the logs of the ggscout pods
100+
kubectl logs -l app.kubernetes.io/name=ggscout
101+
102+
# Verify the service account was created
103+
kubectl get serviceaccount ggscout
104+
105+
# Check if the CronJobs are running
106+
kubectl get cronjobs
107+
```
108+
109+
## Troubleshooting
110+
111+
1. **Service Account Issues**: Ensure the service account name matches between `values.yaml` and `secret.yaml`
112+
2. **Vault Role Binding**: Verify the Vault role is bound to the correct service account and namespace
113+
3. **Network Connectivity**: Ensure ggscout pods can reach your Vault instance
114+
4. **Token Permissions**: Verify the Vault policy grants the necessary permissions
115+
116+
For more detailed troubleshooting, enable debug logging by setting `log_level: debug` in the values.yaml file.

‎charts/ggscout/examples/hashicorpvault-k8s/secret.yaml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
apiVersion: v1
3+
kind: Secret
4+
metadata:
5+
name: ggscout-secrets
6+
stringData:
7+
# Vault Kubernetes authentication role
8+
VAULT_K8S_ROLE: "ggscout"
9+
10+
# GitGuardian API token
11+
GITGUARDIAN_API_KEY: "your_gitguardian_token"

‎charts/ggscout/examples/hashicorpvault-k8s/values.yaml

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
# yaml-language-server: $schema=../../values.schema.json
3+
4+
inventory:
5+
config:
6+
sources:
7+
hashicorpvault:
8+
type: hashicorpvault
9+
vault_address: "https://your-vault-address-here.com"
10+
auth:
11+
auth_mode: "k8s"
12+
k8s:
13+
role: "${VAULT_K8S_ROLE}"
14+
fetch_all_versions: true # Fetch all versions of secrets or not
15+
path: "secret/dev" # Vault path or unspecified
16+
mode: "read/write" # Can be `read`, `write` or `read/write` depending on wether fetch and/or sync are enabled
17+
# To upload, set the gitguardian URL and tokens. Ensure the endpoint path ends with /v1
18+
# This is optional: omit this to prevent uploading and to only test collection.
19+
gitguardian:
20+
endpoint: "https://api.gitguardian.com/v1"
21+
api_token: "${GITGUARDIAN_API_KEY}"
22+
jobs:
23+
# Job to fetch defined sources
24+
fetch:
25+
# Set to `false` to disable the job
26+
enabled: true
27+
# Run every 15 minutes
28+
schedule: '*/15 * * * *'
29+
send: true
30+
# Job to be able to sync/write secrets from GitGuardian into you vault
31+
sync:
32+
# Set to `false` to disable the job
33+
enabled: true
34+
# Run every minute
35+
schedule: '* * * * *'
36+
37+
envFrom:
38+
- secretRef:
39+
name: ggscout-secrets

0 commit comments

Comments
 (0)