update: YAML file explanations: Security Labs #1394 (#1588)

athavr · Raj Athavale · web-flow · commit 40747683c355 · 2025-08-13T13:46:49.000-06:00
Co-authored-by: Raj Athavale &lt;athavr@amazon.com&gt;
diff --git a/website/docs/security/cluster-access-management/kubernetes-rbac.md b/website/docs/security/cluster-access-management/kubernetes-rbac.md
@@ -7,17 +7,20 @@ As previously mentioned, the cluster access management controls and associated A
 
 In this section of the lab, we'll show how to configure access entries with granular permissions using Kubernetes groups. This is useful when the pre-defined access policies are too permissive. As part of the lab setup, we created an IAM role named `eks-workshop-carts-team`. In this scenario, we'll demonstrate how to use that role to provide a team that only works on the **carts** service with permissions that allow them to view all resources in the `carts` namespace, but also delete pods.
 
-First, let's create the Kubernetes objects that model our required permissions. This `Role` provides the permissions we outlined above:
+First, let's create the Kubernetes objects that model our required permissions. This Role provides the permissions we outlined above:
 
-```file
-manifests/modules/security/cam/rbac/role.yaml
-```
+::yaml{file="manifests/modules/security/cam/rbac/role.yaml" paths="metadata.namespace,rules.0,rules.1"}
 
-And this `RoleBinding` will map the role to a group named `carts-team`:
+1. Restrict the Role permissions to apply only to the `carts` namespace
+2. This rule allows read-only operations `verbs: ["get", "list", "watch"]` on all resources `resources: ["*"]`
+3. This rule allows delete operations `verbs: ["delete"]` specific to pods only `resources: ["pods"]`
 
-```file
-manifests/modules/security/cam/rbac/rolebinding.yaml
-```
+And this `RoleBinding` will map the Role to a Group named `carts-team`:
+
+::yaml{file="manifests/modules/security/cam/rbac/rolebinding.yaml" paths="roleRef,subjects.0"}
+
+1. `roleRef` references the `carts-team-role` Role we created earlier 
+2. `subjects` specifies that a Group named `carts-team` will get the permissions associated with the Role
 
 Let's apply these manifests:
 
diff --git a/website/docs/security/guardduty/log-monitoring/privileged_container_mount.md b/website/docs/security/guardduty/log-monitoring/privileged_container_mount.md
@@ -7,11 +7,13 @@ In this lab you will be creating a container with `privileged` Security Context,
 
 This exercise will generate two different findings, `PrivilegeEscalation:Kubernetes/PrivilegedContainer` which indicates that a container was launched with Privileged permissions, and `Persistence:Kubernetes/ContainerWithSensitiveMount` indicating a sensitive external host path mounted inside the container.
 
-To simulate the finding you'll be using a pre-configure manifest with some specific parameters already set, `SecurityContext: privileged: true` and also the `volume` and `volumeMount` options, mapping the `/etc` host directory to `/host-etc` Pod volume mount.
+To simulate the finding you'll be using a pre-configure manifest with some specific parameters already set:
 
-```file
-manifests/modules/security/Guardduty/mount/privileged-pod-example.yaml
-```
+::yaml{file="manifests/modules/security/Guardduty/mount/privileged-pod-example.yaml" paths="spec.containers.0.securityContext,spec.containers.0.volumeMounts.0.mountPath,spec.volumes.0.hostPath.path"}
+
+1. Setting `SecurityContext: privileged: true` grants full root privileges to the Pod
+2. `mountPath: /host-etc` specifies that the mapped host volume will be accessible inside the container at `/host-etc` 
+3. `path: /etc` specifies that `/etc` directory from the host system will be the source directory for the mount
 
 Apply the manifest shown above with the following command:
 
diff --git a/website/docs/security/kyverno/baseline-pss.md b/website/docs/security/kyverno/baseline-pss.md
@@ -22,11 +22,12 @@ To prevent such escalated privileged capabilities and avoid unauthorized use of
 
 The baseline profile of the Pod Security Standards is a collection of the most fundamental and crucial steps that can be taken to secure Pods. Starting from Kyverno 1.8, an entire profile can be assigned to the cluster through a single rule. To learn more about the privileges blocked by the Baseline Profile, please refer to the [Kyverno documentation](https://kyverno.io/policies/#:~:text=Baseline%20Pod%20Security%20Standards,cluster%20through%20a%20single%20rule).
 
-```file
-manifests/modules/security/kyverno/baseline-policy/baseline-policy.yaml
-```
+::yaml{file="manifests/modules/security/kyverno/baseline-policy/baseline-policy.yaml" paths="spec.background,spec.validationFailureAction,spec.rules.0.match,spec.rules.0.validate"}
 
-Note that the above policy is in `Enforce` mode and will block any requests to create privileged Pods.
+1. `background: true` applies the policy to existing resources in addition to new ones
+2. `validationFailureAction: Enforce` blocks non-compliant Pods from being created
+3. `match.any.resources.kinds: [Pod]` applies the policy to all Pod resources cluster-wide
+4. `validate.podSecurity` enforces Kubernetes Pod Security Standards at the `baseline` level with moderate security restrictions using the `latest` standards version
 
 Go ahead and apply the Baseline Policy:
 
diff --git a/website/docs/security/kyverno/creating-policy.md b/website/docs/security/kyverno/creating-policy.md
@@ -3,24 +3,18 @@ title: "Creating a Simple Policy"
 sidebar_position: 71
 ---
 
-To gain an understanding of Kyverno policies, we'll start our lab with a simple Pod label requirement. As you may know, labels in Kubernetes are used to tag resources in the cluster.
+Kyverno has two kinds of Policy resources: **ClusterPolicy** used for Cluster-Wide Resources and **Policy** used for Namespaced Resources. To gain an understanding of Kyverno policies, we'll start our lab with a simple Pod label requirement. As you may know, labels in Kubernetes are used to tag resources in the cluster.
 
-Below is a sample policy requiring a Label `CostCenter`:
+Below is a sample `ClusterPolicy` which will block any Pod creation that doesn't have the label `CostCenter`:
 
-```file
-manifests/modules/security/kyverno/simple-policy/require-labels-policy.yaml
-```
-
-Kyverno has two kinds of Policy resources: **ClusterPolicy** used for Cluster-Wide Resources and **Policy** used for Namespaced Resources. The example above shows a ClusterPolicy. Take some time to examine the following details in the configuration:
+::yaml{file="manifests/modules/security/kyverno/simple-policy/require-labels-policy.yaml" paths="spec.validationFailureAction,spec.rules,spec.rules.0.match,spec.rules.0.validate,spec.rules.0.validate.message,spec.rules.0.validate.pattern"}
 
-- Under the `spec` section of the Policy, there's an attribute `validationFailureAction`. It tells Kyverno if the resource being validated should be allowed but reported (`Audit`) or blocked (`Enforce`). The default is `Audit`, but our example is set to `Enforce`.
-- The `rules` section contains one or more rules to be validated.
-- The `match` statement sets the scope of what will be checked. In this case, it's any `Pod` resource.
-- The `validate` statement attempts to positively check what is defined. If the statement, when compared with the requested resource, is true, it's allowed. If false, it's blocked.
-- The `message` is what gets displayed to a user if this rule fails validation.
-- The `pattern` object defines what pattern will be checked in the resource. In this case, it's looking for `metadata.labels` with `CostCenter`.
-
-This example policy will block any Pod creation that doesn't have the label `CostCenter`.
+1. `spec.validationFailureAction` tells Kyverno if the resource being validated should be allowed but reported (`Audit`) or blocked (`Enforce`). The default is `Audit`, but in our example it is set to `Enforce`
+2. The `rules` section contains one or more rules to be validated
+3. The `match` statement sets the scope of what will be checked. In this case, it's any Pod resource
+4. The `validate` statement attempts to positively check what is defined. If the statement, when compared with the requested resource, is true, it's allowed. If false, it's blocked
+5. The `message` is what gets displayed to a user if this rule fails validation
+6. The `pattern` object defines what pattern will be checked in the resource. In this case, it's looking for `metadata.labels` with `CostCenter`
 
 Create the policy using the following command:
 
@@ -106,13 +100,12 @@ As you can see, the admission webhook successfully validated the Policy and the
 
 In the above examples, you checked how Validation Policies work in their default behavior defined in `validationFailureAction`. However, Kyverno can also be used to manage Mutating rules within the Policy, to modify any API Requests to satisfy or enforce the specified requirements on the Kubernetes resources. The resource mutation occurs before validation, so the validation rules will not contradict the changes performed by the mutation section.
 
-Below is a sample Policy with a mutation rule defined, which will be used to automatically add our label `CostCenter=IT` as default to any `Pod`:
+Below is a sample Policy with a mutation rule defined:
 
-```file
-manifests/modules/security/kyverno/simple-policy/add-labels-mutation-policy.yaml
-```
+::yaml{file="manifests/modules/security/kyverno/simple-policy/add-labels-mutation-policy.yaml" paths="spec.rules.0.match,spec.rules.0.mutate"}
 
-Notice the `mutate` section under the ClusterPolicy `spec`.
+1. `match.any.resources.kinds: [Pod]` targets this `ClusterPolicy` to all Pod resources cluster-wide
+2.  `mutate` modifies resources during creation (vs. validate which blocks/allows). `patchStrategicMerge.metadata.labels.CostCenter: IT` automatically adds `CostCenter: IT` label to every Pod
 
 Go ahead and create the above Policy using the following command:
 
diff --git a/website/docs/security/kyverno/restricting-images.md b/website/docs/security/kyverno/restricting-images.md
@@ -26,9 +26,12 @@ To implement best practices, we'll define a policy that restricts the use of una
 
 For this lab, we'll use the [Amazon ECR Public Gallery](https://public.ecr.aws/) as our trusted registry, blocking any containers that use images hosted in other registries. Here's a sample Kyverno policy to restrict image pulling for this use case:
 
-```file
-manifests/modules/security/kyverno/images/restrict-registries.yaml
-```
+::yaml{file="manifests/modules/security/kyverno/images/restrict-registries.yaml" paths="spec.validationFailureAction,spec.background,spec.rules.0.match,spec.rules.0.validate.pattern"}
+
+1. `validationFailureAction: Enforce` blocks non-compliant Pods from being created
+2. `background: true` applies the policy to existing resources in addition to new ones
+3. `match.any.resources.kinds: [Pod]` applies the policy to all Pod resources cluster-wide
+4. `validate.pattern` enforces that all container images must originate from the `public.ecr.aws/*` registry, blocking any images from unauthorized registries
 
 > Note: This policy doesn't restrict the usage of InitContainers or Ephemeral Containers to the referred repository.
 
diff --git a/website/docs/security/secrets-management/secrets-manager/ascp.md b/website/docs/security/secrets-management/secrets-manager/ascp.md
@@ -35,43 +35,17 @@ pod/secrets-store-csi-driver-provider-aws-dzg9r   1/1     Running   0          2
 
 To provide access to secrets stored in AWS Secrets Manager via the CSI driver, you'll need a `SecretProviderClass` - a namespaced custom resource that provides driver configurations and parameters matching the information in AWS Secrets Manager.
 
-```file
-manifests/modules/security/secrets-manager/secret-provider-class.yaml
-```
+::yaml{file="manifests/modules/security/secrets-manager/secret-provider-class.yaml" paths="spec.provider,spec.parameters.objects,spec.secretObjects.0"}
+
+1. `provider: aws` specifies AWS Secrets Store CSI driver
+2. `parameters.objects` defines the AWS `secretsmanager` source secret named `$SECRET_NAME` and uses [jmesPath](https://jmespath.org/) to extract specific `username` and `password` fields into named aliases for Kubernetes consumption
+3. `secretObjects` creates a standard `Opaque` Kubernetes secret named `catalog-secret` that maps the extracted `username` and `password` fields to secret keys
 
-Let's create this resource and examine its two main configuration sections:
+Let's create this resource:
 
 ```bash
 $ cat ~/environment/eks-workshop/modules/security/secrets-manager/secret-provider-class.yaml \
   | envsubst | kubectl apply -f -
 ```
 
-First, the `objects` parameter points to a secret named `$SECRET_NAME` that we created in AWS Secrets Manager in the previous step. Note that we're using [jmesPath](https://jmespath.org/) to extract specific key-value pairs from the JSON-formatted secret:
-
-```bash
-$ kubectl get secretproviderclass -n catalog catalog-spc -o yaml | yq '.spec.parameters.objects'
-
-- objectName: "eks-workshop-catalog-secret-WDD8yS"
-  objectType: "secretsmanager"
-  jmesPath:
-    - path: username
-      objectAlias: username
-    - path: password
-      objectAlias: password
-```
-
-Second, the `secretObjects` section defines how to create and sync a Kubernetes Secret with data from the AWS Secrets Manager secret. When mounted to a Pod, the SecretProviderClass will create a Kubernetes Secret (if it doesn't exist) named `catalog-secret` and sync the values from AWS Secrets Manager:
-
-```bash
-$ kubectl get secretproviderclass -n catalog catalog-spc -o yaml | yq '.spec.secretObjects'
-
-- data:
-    - key: username
-      objectName: username
-    - key: password
-      objectName: password
-  secretName: catalog-secret
-  type: Opaque
-```
-
 The Secret Store CSI Driver acts as an intermediary between Kubernetes and external secrets providers like AWS Secrets Manager. When configured with a SecretProviderClass, it can both mount secrets as files in Pod volumes and create synchronized Kubernetes Secret objects, providing flexibility in how applications consume these secrets.
diff --git a/website/docs/security/secrets-management/secrets-manager/external-secrets.md b/website/docs/security/secrets-management/secrets-manager/external-secrets.md
@@ -24,37 +24,21 @@ $ kubectl -n external-secrets describe sa external-secrets-sa | grep Annotations
 Annotations:         eks.amazonaws.com/role-arn: arn:aws:iam::1234567890:role/eks-workshop-external-secrets-sa-irsa
 ```
 
-We need to create a `ClusterSecretStore` resource - this is a cluster-wide SecretStore that can be referenced by ExternalSecrets from any namespace:
+We need to create a `ClusterSecretStore` resource - this is a cluster-wide SecretStore that can be referenced by ExternalSecrets from any namespace. Lets inspect the file we will use to create this `ClusterSecretStore`:
 
-```file
-manifests/modules/security/secrets-manager/cluster-secret-store.yaml
-```
+::yaml{file="manifests/modules/security/secrets-manager/cluster-secret-store.yaml" paths="spec.provider.aws.service,spec.provider.aws.region,spec.provider.aws.auth.jwt"}
 
-```bash
-$ cat ~/environment/eks-workshop/modules/security/secrets-manager/cluster-secret-store.yaml \
-  | envsubst | kubectl apply -f -
-```
+1. Set `service: SecretsManager` to use AWS Secrets Manager as the secret source
+2. Use the `$AWS_REGION` environment variable to specify the AWS region where secrets are stored
+3. `auth.jwt` uses IRSA to authenticate via the `external-secrets-sa` service account in the `external-secrets` namespace, which is linked to an IAM role with AWS Secrets Manager permissions
 
-Let's examine the specifications of this newly created resource:
+Lets use this file to create the ClusterSecretStore resource.
 
 ```bash
-$ kubectl get clustersecretstores.external-secrets.io
-NAME                   AGE   STATUS   CAPABILITIES   READY
-cluster-secret-store   81s   Valid    ReadWrite      True
-$ kubectl get clustersecretstores.external-secrets.io cluster-secret-store  -o yaml | yq '.spec'
-provider:
-  aws:
-    auth:
-      jwt:
-        serviceAccountRef:
-          name: external-secrets-sa
-          namespace: external-secrets
-    region: us-west-2
-    service: SecretsManager
+$ cat ~/environment/eks-workshop/modules/security/secrets-manager/cluster-secret-store.yaml \
+  | envsubst | kubectl apply -f -
 ```
 
-The ClusterSecretStore uses a [JSON Web Token (JWT)](https://jwt.io/) referenced to our ServiceAccount to authenticate with AWS Secrets Manager.
-
 Next, we'll create an `ExternalSecret` that defines what data should be fetched from AWS Secrets Manager and how it should be transformed into a Kubernetes Secret. We'll then update our `catalog` Deployment to use these credentials:
 
 ```kustomization
