### Install Piggy via Helm

Source: https://github.com/kongz/piggy/blob/main/README.md

Commands to add the Piggy repository and install the webhooks chart.

```bash
helm repo add piggysec https://piggysec.com
helm -n piggy-webhooks install piggy-webhooks piggysec/piggy-webhooks --set aws.roleArn=${piggy-role-arn}
```

--------------------------------

### Install Piggy Webhooks with Helm flags

Source: https://github.com/kongz/piggy/blob/main/demo/default-value/README.md

Use this command to install the chart directly with specific configuration overrides.

```bash
helm -n piggy-webhooks install piggy-webhooks piggysec/piggy-webhooks \
  --set aws.roleArn=${piggy-role-arn} \
  --set env.AWS_REGION=ap-southeast-1 \
  --set env.PIGGY_DEFAULT_SECRET_NAME_SUFFIX=/test
```

--------------------------------

### Install Piggy Webhooks using a values file

Source: https://github.com/kongz/piggy/blob/main/demo/default-value/README.md

Deploy the chart using the previously defined values.yaml file.

```bash
helm -n piggy-webhooks install piggy-webhooks piggysec/piggy-webhooks -f values.yaml
```

--------------------------------

### Install Piggy Webhooks via Helm

Source: https://github.com/kongz/piggy/blob/main/charts/piggy-webhooks/README.md

Adds the repository and installs the chart with the required AWS IAM role ARN.

```bash
helm repo add piggysec https://piggysec.com
helm install piggy-webhooks piggysec/piggy-webhooks \
  --namespace piggy-webhooks \
  --create-namespace \
  --set aws.roleArn=arn:aws:iam::123456789012:role/piggy-webhooks-role
```

--------------------------------

### Example Piggy Webhooks log output

Source: https://github.com/kongz/piggy/blob/main/docs/troubleshooting.md

Sample JSON log entries showing pod mutation and successful request processing.

```json
{"level":"info","namespace":"my-ns","owner":"my-pod","time":"2026-01-27T11:27:47Z","message":"Pod of ReplicaSet 'my-pod' has been mutated (took 30.701µs)"}
{"level":"info","namespace":"my-ns","pod_name":"my-pod","service_account":"my-ns:my-sa","secret_name":"my-ns/my-sa","time":"2026-01-27T12:30:02Z","message":"Request from [sa=my-ns:my-sa], [pod=my-pod] was successful"}
```

--------------------------------

### Example piggy-env log output

Source: https://github.com/kongz/piggy/blob/main/docs/troubleshooting.md

Sample JSON log entry indicating a successful secret request.

```json
{"level":"info","time":"2026-01-27T12:37:19Z","message":"Request secrets was successful"}
```

--------------------------------

### Configure Pod for Standalone Mode

Source: https://github.com/kongz/piggy/blob/main/README.md

Example Pod manifest configured for standalone mode, requiring specific annotations and IRSA volume mounts.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: myapp
  annotations:
    piggysec.com/aws-secret-name: omise-staging/sample/test
    piggysec.com/aws-region: ap-southeast-1
    piggysec.com/standalone: "true"
spec:
  serviceAccount: myapp
  containers:
    - image: myapp:v1
      name: myapp
      volumeMounts:
        - mountPath: /var/run/secrets/eks.amazonaws.com/serviceaccount
          name: aws-iam-token
          readOnly: true
      env:
        - name: TEST_ENV
          value: piggy:TEST_ENV
        - name: AWS_ROLE_ARN
          value: ${your-role-arn}
        - name: AWS_WEB_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/eks.amazonaws.com/serviceaccount/token
  volumes:
    - name: aws-iam-token
      projected:
        defaultMode: 420
        sources:
          - serviceAccountToken:
              audience: sts.amazonaws.com
              expirationSeconds: 86400
              path: token
```

--------------------------------

### Configure Default Settings in Helm

Source: https://github.com/kongz/piggy/blob/main/README.md

Example of setting default environment variables in the Piggy Webhooks Helm chart.

```yaml
env:
  AWS_REGION: "ap-southeast-1"
  PIGGY_ENFORCE_SERVICE_ACCOUNT: "true"
```

--------------------------------

### PIGGY_ALLOWED_SA Configuration

Source: https://github.com/kongz/piggy/blob/main/README.md

Example value format for restricting secret access to specific service accounts.

```bash
myapp-namespace:myapp,myanotherapp-namespace:default
```

--------------------------------

### Accessing Injected Environment Variables

Source: https://github.com/kongz/piggy/blob/main/README.md

Example of reading the injected secret value from an environment variable in Go.

```go
func main() {
  val := os.Getenv("TEST_ENV")
  fmt.Printf("%s", val)
}
```

--------------------------------

### Clone the repository

Source: https://github.com/kongz/piggy/blob/main/CONTRIBUTING.md

Initial command to download the project source code.

```bash
git clone https://github.com/KongZ/piggy.git
```

--------------------------------

### Build the project locally

Source: https://github.com/kongz/piggy/blob/main/CONTRIBUTING.md

Compiles the piggy-webhooks binary from the source.

```bash
cd piggy-webhooks
go build -o piggy-webhooks
```

--------------------------------

### Kubernetes Admission Workflow Diagram

Source: https://github.com/kongz/piggy/blob/main/README.md

Visual representation of the pod creation and secret injection process via Piggy webhooks.

```bash
 (1)   ┌───────────┐  (2)   ┌───────────┐ (5)   ┌───────────┐ (6)   ┌───────────┐
 ───▶  │           │  ───▶  │ Mutating  │ ───▶  │  Object   │ ───▶  │           │
───────│Create Pod │────────│ Admission │───────│Validation │───────│ Persisted │
       │           │        │           │       │           │       │           │
       └───────────┘        └───────────┘       └───────────┘       └───────────┘
                                  │
                                «tls»
                                  │▲
                                 │││(4)
                              (3)│││
                                 ▼│
                            ┌───────────┐
                            │   Piggy   │
                            │ Webhooks  │
                            │           │
                            └───────────┘
```

--------------------------------

### Create a feature branch

Source: https://github.com/kongz/piggy/blob/main/CONTRIBUTING.md

Command to initialize a new branch for development.

```bash
git checkout -b feature/your-feature
```

--------------------------------

### Configure Piggy Webhooks with a values file

Source: https://github.com/kongz/piggy/blob/main/demo/default-value/README.md

Define configuration settings in a YAML file for cleaner deployment management.

```yaml
aws:
  roleArn: arn:aws:iam::123456789:role/piggy-webhooks

env:
  AWS_REGION: "ap-southeast-1"
  PIGGY_DEFAULT_SECRET_NAME_PREFIX: ""
  PIGGY_DEFAULT_SECRET_NAME_SUFFIX: "/test"
```

--------------------------------

### Verify Environment Variable Resolution

Source: https://github.com/kongz/piggy/blob/main/docs/demo.md

Commands to check the raw environment variable and verify resolution via the demo application.

```bash
> echo $TEST_ENV
> piggy:TEST_ENV
```

```bash
> curl -s localhost:8080 | grep TEST_ENV
> TEST_ENV=hello world
```

--------------------------------

### Retrieve Application URL via Helm Templates

Source: https://github.com/kongz/piggy/blob/main/charts/piggy-webhooks/templates/NOTES.txt

These templates dynamically generate access instructions based on the service configuration defined in values.yaml.

```helm
{{- if .Values.ingress.enabled }}
{{- range $host := .Values.ingress.hosts }}
  {{- range .paths }}
  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
  {{- end }}
{{- end }}
{{- else if contains "NodePort" .Values.service.type }}
  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "piggy-webhooks.fullname" . }})
  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
  echo http://$NODE_IP:$NODE_PORT
{{- else if contains "LoadBalancer" .Values.service.type }}
     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
           You can watch the status of by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "piggy-webhooks.fullname" . }}'
  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "piggy-webhooks.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
  echo http://$SERVICE_IP:{{ .Values.service.port }}
{{- else if contains "ClusterIP" .Values.service.type }}
  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "piggy-webhooks.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
  echo "Visit http://127.0.0.1:8080 to use your application"
  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
{{- end }}
```

--------------------------------

### Run project tests

Source: https://github.com/kongz/piggy/blob/main/CONTRIBUTING.md

Executes the test suite for the piggy-webhooks package.

```bash
cd piggy-webhooks
go test -v ./...
```

--------------------------------

### Configure Pod for SSM Parameter Store

Source: https://github.com/kongz/piggy/blob/main/docs/demo.md

Kubernetes Pod manifest with annotations for Piggy webhook integration and environment variable mapping.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: demo
  annotations:
    piggysec.com/piggy-address: https://piggy-webhooks.piggy-webhooks.svc.cluster.local
    piggysec.com/aws-ssm-parameter-path: demo/sample/test
    piggysec.com/aws-region: ap-southeast-1
spec:
  containers:
    - image: ghcr.io/kongz/piggy-demo:latest
      name: demo
      env:
        - name: TEST_ENV
          value: piggy:TEST_ENV
        - name: TEST_LIST
          value: piggy:TEST_LIST
        - name: TEST_PLAIN
          value: piggy:TEST_PLAIN
      resources:
        limits:
          memory: "64Mi"
          cpu: "200m"
```

--------------------------------

### Configure Demo Pod with Piggy Annotations

Source: https://github.com/kongz/piggy/blob/main/docs/demo.md

Kubernetes Pod manifest configured with Piggy annotations to enable secret injection.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: demo
  annotations:
    piggysec.com/piggy-address: https://piggy-webhooks.piggy-webhooks.svc.cluster.local
    piggysec.com/aws-secret-name: demo/sample/test
    piggysec.com/aws-region: ap-southeast-1
spec:
  containers:
    - image: ghcr.io/kongz/piggy-demo:latest
      name: demo
      env:
        - name: TEST_ENV
          value: piggy:TEST_ENV
      resources:
        limits:
          memory: "64Mi"
          cpu: "200m"
```

--------------------------------

### Proxy Mode Architecture Diagram

Source: https://github.com/kongz/piggy/blob/main/docs/how-it-works.md

Visual representation of the Piggy proxy mode workflow and interactions between Kubernetes, AWS STS, and AWS Secrets Manager.

```bash
                (1)  ┌───────────┐ (10)
                ───▶ │           │ ───▶
              ───────│ Container │───────
                     │           │
                     └───────────┘
                           │
                         «tls»
                           │
                          ││▲
                       (2)│││(9)
                          ▼││
┌───────────┐  (3)   ┌───────────┐  (5)   ┌───────────┐
│Kubernetes │  ◀───  │   Piggy   │  ───▶  │           │
│    API    │────────│ Webhooks  │────────│  AWS STS  │
│           │  ───▶  │           │  ◀───  │           │
└───────────┘   (4)  └───────────┘   (6)  └───────────┘
                           │▲
                          │││(8)
                       (7)│││
                          ▼│
                     ┌───────────┐
                     │AWS Secret │
                     │  Manager  │
                     │           │
                     └───────────┘
```

--------------------------------

### Configure Match Conditions for Webhook Optimization

Source: https://github.com/kongz/piggy/blob/main/charts/piggy-webhooks/README.md

Uses CEL expressions to pre-filter pods at the API server level, reducing webhook load. Recommended for Kubernetes 1.27 and later.

```yaml
mutate:
  matchConditions:
    - name: "include-piggy-pods"
      expression: |
        has(object.metadata.annotations) && (
          'piggysec.com/piggy-address' in object.metadata.annotations ||
          'piggysec.com/aws-secret-name' in object.metadata.annotations ||
          'piggysec.com/aws-ssm-parameter-path' in object.metadata.annotations
        )
```

--------------------------------

### Retrieve Piggy Webhooks logs

Source: https://github.com/kongz/piggy/blob/main/docs/troubleshooting.md

Use this command to view logs for the Piggy Webhooks deployment in the specified namespace.

```bash
kubectl -n piggy-webhooks logs deployment/piggy-webhooks
```

--------------------------------

### Retrieve piggy-env logs

Source: https://github.com/kongz/piggy/blob/main/docs/troubleshooting.md

Use this command to view logs for a specific piggy-env pod within a namespace.

```bash
kubectl -n <namespace> logs <pod-name>
```

--------------------------------

### Check test coverage

Source: https://github.com/kongz/piggy/blob/main/CONTRIBUTING.md

Generates and views a coverage report for the project.

```bash
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

--------------------------------

### Configure Pod Annotations

Source: https://github.com/kongz/piggy/blob/main/README.md

Required annotations for a Pod to enable secret injection by Piggy.

```yaml
apiVersion: v1
kind: Pod
metadata:
  annotations:
    piggysec.com/piggy-address: https://piggy-webhooks.piggy-webhooks.svc.cluster.local
    piggysec.com/aws-secret-name: ${your-aws-secret-name} ## e.g. myapp/sample/production
    piggysec.com/aws-region: ${your-aws-secret-region} ## e.g. ap-southeast-1
```

--------------------------------

### Configure Object Selector in values.yaml

Source: https://github.com/kongz/piggy/blob/main/docs/optimizing-webhook.md

Define matchLabels to restrict webhook invocations to pods explicitly labeled for mutation.

```yaml
mutate:
  objectSelector:
    matchLabels:
      piggysec.com/mutate: "true"
```

--------------------------------

### Verify Secret Resolution via cURL

Source: https://github.com/kongz/piggy/blob/main/docs/demo.md

Command to verify that environment variables are correctly resolved by the application.

```bash
> curl -s localhost:8080 | grep TEST_ENV
> TEST_ENV=hello world
```

--------------------------------

### Apply Mutation Label to Pod

Source: https://github.com/kongz/piggy/blob/main/docs/optimizing-webhook.md

Add the required label to the Pod metadata to trigger the webhook.

```yaml
metadata:
  labels:
    piggysec.com/mutate: "true"
```

--------------------------------

### Inject Secret via Environment Variable

Source: https://github.com/kongz/piggy/blob/main/README.md

Format for referencing secrets in container environment variables.

```yaml
containers:
  env:
    - name: TEST_ENV
      value: piggy:TEST_ENV
```

--------------------------------

### Define Environment Variables for Piggy

Source: https://github.com/kongz/piggy/blob/main/README.md

Reference the secrets retrieved from the parameter path using the piggy: prefix in environment variable values.

```yaml
- name: TEST_ENV
  value: piggy:TEST_ENV
- name: TEST_LIST
  value: piggy:TEST_LIST
- name: TEST_PLAIN
  value: piggy:TEST_PLAIN
```

--------------------------------

### Define ServiceAccount for Standalone Mode

Source: https://github.com/kongz/piggy/blob/main/README.md

ServiceAccount manifest with the required IAM role ARN annotation for IRSA.

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: myapp
  annotations:
    eks.amazonaws.com/role-arn: ${your-role-arn}
```

--------------------------------

### IAM Policy for SSM and ECR Access

Source: https://github.com/kongz/piggy/blob/main/README.md

Minimum required IAM policy to allow Piggy to read parameters from SSM and access ECR images.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PiggySSM",
      "Effect": "Allow",
      "Action": ["ssm:GetParametersByPath"],
      "Resource": "*"
    },
    {
      "Sid": "PiggyECRReadOnly",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:GetAuthorizationToken",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

--------------------------------

### Configure SSM Parameter Path Annotation

Source: https://github.com/kongz/piggy/blob/main/README.md

Use this annotation to specify the parameter path in AWS SSM for secret retrieval.

```yaml
piggysec.com/aws-ssm-parameter-path: /demo/sample/test
```

--------------------------------

### Define IRSA Policy for SSM Parameter Store

Source: https://github.com/kongz/piggy/blob/main/docs/demo.md

IAM policy granting permissions for SSM parameter retrieval and ECR read access.

```yaml
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "piggySSM",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParametersByPath"
      ],
      "Resource": "*"
    },
    {
      "Sid": "PiggyECRReadOnly",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:GetAuthorizationToken",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

--------------------------------

### Define AWS IAM Policy for Piggy

Source: https://github.com/kongz/piggy/blob/main/README.md

Required IAM policy permissions for the Pod service account to access secrets in AWS Secrets Manager when using standalone mode.

```yaml
{
  "Version": "2012-10-17",
  "Statement":
    [
      {
        "Sid": "PiggySecretReadOnly",
        "Action":
          [
            "secretsmanager:DescribeSecret",
            "secretsmanager:GetResourcePolicy",
            "secretsmanager:GetSecretValue",
            "secretsmanager:ListSecretVersionIds",
            "secretsmanager:ListSecrets",
          ],
        "Effect": "Allow",
        "Resource": "${your-secret-name-arn}",
      },
    ],
}
```

--------------------------------

### Define IRSA IAM Policy for Piggy

Source: https://github.com/kongz/piggy/blob/main/docs/demo.md

IAM policy granting read-only access to Secrets Manager and ECR for the Piggy webhooks service account.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PiggySecretReadOnly",
      "Action": [
        "secretsmanager:DescribeSecret",
        "secretsmanager:GetResourcePolicy",
        "secretsmanager:GetSecretValue",
        "secretsmanager:ListSecretVersionIds",
        "secretsmanager:ListSecrets"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Sid": "PiggyECRReadOnly",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:GetAuthorizationToken",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.