Fix links and markdown format for some pages

content/en/docs/concepts/policy/pod-security-policy.md

@@ -23,7 +23,8 @@ updates.
 ## What is a Pod Security Policy?
 
 A _Pod Security Policy_ is a cluster-level resource that controls security
-sensitive aspects of the pod specification. The [PodSecurityPolicy](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritypolicy-v1beta1-policy) objects
+sensitive aspects of the pod specification. The
+[PodSecurityPolicy](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritypolicy-v1beta1-policy) objects
 define a set of conditions that a pod must run with in order to be accepted into
 the system, as well as defaults for the related fields. They allow an
 administrator to control the following:
@@ -50,10 +51,10 @@ administrator to control the following:
 
 ## Enabling Pod Security Policies
 
-Pod security policy control is implemented as an optional [admission
+Pod security policy control is implemented as an optional
-controller](/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy).
+[admission controller](/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy).
-PodSecurityPolicies are enforced by [enabling the admission
+PodSecurityPolicies are enforced by
-controller](/docs/reference/access-authn-authz/admission-controllers/#how-do-i-turn-on-an-admission-control-plug-in),
+[enabling the admission controller](/docs/reference/access-authn-authz/admission-controllers/#how-do-i-turn-on-an-admission-control-plug-in),
 but doing so without authorizing any policies **will prevent any pods from being created** in the
 cluster.
 
@@ -65,9 +66,9 @@ controller.
 ## Authorizing Policies
 
 When a PodSecurityPolicy resource is created, it does nothing. In order to use
-it, the requesting user or target pod's [service
+it, the requesting user or target pod's
-account](/docs/tasks/configure-pod-container/configure-service-account/) must be
+[service account](/docs/tasks/configure-pod-container/configure-service-account/)
-authorized to use the policy, by allowing the `use` verb on the policy.
+must be authorized to use the policy, by allowing the `use` verb on the policy.
 
 Most Kubernetes pods are not created directly by users. Instead, they are
 typically created indirectly as part of a
@@ -128,6 +129,7 @@ subjects:
 If a `RoleBinding` (not a `ClusterRoleBinding`) is used, it will only grant
 usage for pods being run in the same namespace as the binding. This can be
 paired with system groups to grant access to all pods run in the namespace:
+
 ```yaml
 # Authorize all service accounts in a namespace:
 - kind: Group
@@ -139,25 +141,27 @@ paired with system groups to grant access to all pods run in the namespace:
   name: system:authenticated
 ```
 
-For more examples of RBAC bindings, see [Role Binding
+For more examples of RBAC bindings, see
-Examples](/docs/reference/access-authn-authz/rbac#role-binding-examples).
+[RoleBinding examples](/docs/reference/access-authn-authz/rbac#role-binding-examples).
-For a complete example of authorizing a PodSecurityPolicy, see
+For a complete example of authorizing a PodSecurityPolicy, see [below](#example).
-[below](#example).
 
 ### Recommended Practice
 
-PodSecurityPolicy is being replaced by a new, simplified `PodSecurity` {{< glossary_tooltip
+PodSecurityPolicy is being replaced by a new, simplified `PodSecurity`
-text="admission controller" term_id="admission-controller" >}}. For more details on this change, see
+{{< glossary_tooltip text="admission controller" term_id="admission-controller" >}}.
-[PodSecurityPolicy Deprecation: Past, Present, and
+For more details on this change, see
-Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/). Follow these
+[PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/).
-guidelines to simplify migration from PodSecurityPolicy to the new admission controller:
+Follow these guidelines to simplify migration from PodSecurityPolicy to the
+new admission controller:
+
+1. Limit your PodSecurityPolicies to the policies defined by the
+   [Pod Security Standards](/docs/concepts/security/pod-security-standards):
 
-1. Limit your PodSecurityPolicies to the policies defined by the [Pod Security Standards](/docs/concepts/security/pod-security-standards):
    - {{< example file="policy/privileged-psp.yaml" >}}Privileged{{< /example >}}
    - {{< example file="policy/baseline-psp.yaml" >}}Baseline{{< /example >}}
    - {{< example file="policy/restricted-psp.yaml" >}}Restricted{{< /example >}}
 
-2. Only bind PSPs to entire namespaces, by using the `system:serviceaccounts:<namespace>` group
+1. Only bind PSPs to entire namespaces, by using the `system:serviceaccounts:<namespace>` group
    (where `<namespace>` is the target namespace). For example:
 
    ```yaml
@@ -213,8 +217,8 @@ only non-mutating PodSecurityPolicies are used to validate the pod.
 
 ## Example
 
-_This example assumes you have a running cluster with the PodSecurityPolicy
+This example assumes you have a running cluster with the PodSecurityPolicy
-admission controller enabled and you have cluster admin privileges._
+admission controller enabled and you have cluster admin privileges.
 
 ### Set up
 
@@ -360,12 +364,24 @@ Let's try that again, slightly differently:
 
 ```shell
 kubectl-user create deployment pause --image=k8s.gcr.io/pause
+```
+
+```none
 deployment "pause" created
-
+```
+```shell
 kubectl-user get pods
-No resources found.
+```
 
+```
+No resources found.
+```
+
+```shell
 kubectl-user get events | head -n 2
+```
+
+```
 LASTSEEN   FIRSTSEEN   COUNT     NAME              KIND         SUBOBJECT                TYPE      REASON                  SOURCE                                  MESSAGE
 1m         2m          15        pause-7774d79b5   ReplicaSet                            Warning   FailedCreate            replicaset-controller                   Error creating: pods "pause-7774d79b5-" is forbidden: no providers available to validate pod request
 ```
@@ -386,6 +402,9 @@ is `default`:
 kubectl-admin create rolebinding default:psp:unprivileged \
     --role=psp:unprivileged \
     --serviceaccount=psp-example:default
+```
+
+```none
 rolebinding "default:psp:unprivileged" created
 ```
 
@@ -394,6 +413,9 @@ eventually succeed in creating the pod:
 
 ```shell
 kubectl-user get pods --watch
+```
+
+```none
 NAME                    READY     STATUS    RESTARTS   AGE
 pause-7774d79b5-qrgcb   0/1       Pending   0         1s
 pause-7774d79b5-qrgcb   0/1       Pending   0         1s
@@ -407,6 +429,9 @@ Delete the namespace to clean up most of the example resources:
 
 ```shell
 kubectl-admin delete ns psp-example
+```
+
+```
 namespace "psp-example" deleted
 ```
 
@@ -415,6 +440,9 @@ up separately:
 
 ```shell
 kubectl-admin delete psp example
+```
+
+```
 podsecuritypolicy "example" deleted
 ```
 
@@ -431,7 +459,8 @@ several security mechanisms.
 
 {{< codenew file="policy/restricted-psp.yaml" >}}
 
-See [Pod Security Standards](/docs/concepts/security/pod-security-standards/#policy-instantiation) for more examples.
+See [Pod Security Standards](/docs/concepts/security/pod-security-standards/#policy-instantiation)
+for more examples.
 
 ## Policy Reference
 
@@ -467,17 +496,17 @@ and `max`(inclusive). Defaults to no allowed host ports.
 **Volumes** - Provides a list of allowed volume types. The allowable values
 correspond to the volume sources that are defined when creating a volume. For
 the complete list of volume types, see [Types of
-Volumes](/docs/concepts/storage/volumes/#types-of-volumes). Additionally, `*`
+Volumes](/docs/concepts/storage/volumes/#types-of-volumes). Additionally,
-may be used to allow all volume types.
+`*` may be used to allow all volume types.
 
 The **recommended minimum set** of allowed volumes for new PSPs are:
 
-- configMap
+- `configMap`
-- downwardAPI
+- `downwardAPI`
-- emptyDir
+- `emptyDir`
-- persistentVolumeClaim
+- `persistentVolumeClaim`
-- secret
+- `secret`
-- projected
+- `projected`
 
 {{< warning >}}
 PodSecurityPolicy does not limit the types of `PersistentVolume` objects that
@@ -511,7 +540,8 @@ For example:
       readOnly: true # only allow read-only mounts
 ```
 
-{{< warning >}}There are many ways a container with unrestricted access to the host
+{{< warning >}}
+There are many ways a container with unrestricted access to the host
 filesystem can escalate privileges, including reading data from other
 containers, and abusing the credentials of system services, such as Kubelet.
 
@@ -623,8 +653,8 @@ added. Capabilities listed in `RequiredDropCapabilities` must not be included in
 `AllowedCapabilities` or `DefaultAddCapabilities`.
 
 **DefaultAddCapabilities** - The capabilities which are added to containers by
-default, in addition to the runtime defaults. See the [Docker
+default, in addition to the runtime defaults. See the
-documentation](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
+[Docker documentation](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
 for the default list of capabilities when using the Docker runtime.
 
 ### SELinux
@@ -651,16 +681,17 @@ denoted as the string `Unmasked`.
 
 ### AppArmor
 
-Controlled via annotations on the PodSecurityPolicy. Refer to the [AppArmor
+Controlled via annotations on the PodSecurityPolicy. Refer to the
-documentation](/docs/tutorials/clusters/apparmor/#podsecuritypolicy-annotations).
+[AppArmor documentation](/docs/tutorials/security/apparmor/#podsecuritypolicy-annotations).
 
 ### Seccomp
 
 As of Kubernetes v1.19, you can use the `seccompProfile` field in the
-`securityContext` of Pods or containers to [control use of seccomp
+`securityContext` of Pods or containers to
-profiles](/docs/tutorials/clusters/seccomp). In prior versions, seccomp was
+[control use of seccomp profiles](/docs/tutorials/security/seccomp/).
-controlled by adding annotations to a Pod. The same PodSecurityPolicies can be
+In prior versions, seccomp was controlled by adding annotations to a Pod. The
-used with either version to enforce how these fields or annotations are applied.
+same PodSecurityPolicies can be used with either version to enforce how these
+fields or annotations are applied.
 
 **seccomp.security.alpha.kubernetes.io/defaultProfileName** - Annotation that
 specifies the default seccomp profile to apply to containers. Possible values
@@ -692,18 +723,22 @@ default cannot be changed.
 
 By default, all safe sysctls are allowed. 
 
-- `forbiddenSysctls` - excludes specific sysctls. You can forbid a combination of safe and unsafe sysctls in the list. To forbid setting any sysctls, use `*` on its own.
+- `forbiddenSysctls` - excludes specific sysctls. You can forbid a combination
-- `allowedUnsafeSysctls` - allows specific sysctls that had been disallowed by the default list, so long as these are not listed in `forbiddenSysctls`.
+  of safe and unsafe sysctls in the list. To forbid setting any sysctls, use
+  `*` on its own.
+- `allowedUnsafeSysctls` - allows specific sysctls that had been disallowed by
+  the default list, so long as these are not listed in `forbiddenSysctls`.
 
-Refer to the [Sysctl documentation](
+Refer to the [Sysctl documentation](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy).
-/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy).
 
 ## {{% heading "whatsnext" %}}
 
-- See [PodSecurityPolicy Deprecation: Past, Present, and
+- See [PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/)
-  Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/) to learn about
+  to learn about the future of pod security policy.
-  the future of pod security policy.
 
-- See [Pod Security Standards](/docs/concepts/security/pod-security-standards/) for policy recommendations.
+- See [Pod Security Standards](/docs/concepts/security/pod-security-standards/)
+  for policy recommendations.
+
+- Refer to [PodSecurityPolicy reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritypolicy-v1beta1-policy)
+  for the API details.
 
-- Refer to [Pod Security Policy Reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritypolicy-v1beta1-policy) for the api details.

content/en/docs/reference/using-api/deprecation-policy.md

@@ -85,7 +85,7 @@ might have to add an equivalent field or represent it as an annotation.
    * **Beta API versions must be supported for 9 months or 3 releases (whichever is longer) after deprecation**
    * **Alpha API versions may be removed in any release without prior deprecation notice**
 
-This ensures beta API support covers the [maximum supported version skew of 2 releases](/docs/setup/release/version-skew-policy/).
+This ensures beta API support covers the [maximum supported version skew of 2 releases](/releases/version-skew-policy/).
 
 {{< note >}}
 There are no current plans for a major version revision of Kubernetes that removes GA APIs.

content/en/docs/tutorials/security/ns-level-pss.md

@@ -8,21 +8,23 @@ weight: 10
 This tutorial applies only for new clusters.
 {{% /alert %}}
 
-Pod Security admission (PSA) is enabled by default in v1.23 and later, as it [graduated
+Pod Security admission (PSA) is enabled by default in v1.23 and later, as it
-to beta](/blog/2021/12/09/pod-security-admission-beta/). Pod Security Admission
+[graduated to beta](/blog/2021/12/09/pod-security-admission-beta/). Pod Security Admission
 is an admission controller that applies 
-[Pod Security Standards](docs/concepts/security/pod-security-standards/) 
+[Pod Security Standards](/docs/concepts/security/pod-security-standards/) 
 when pods are created. In this tutorial, you will enforce the `baseline` Pod Security Standard,
 one namespace at a time.
 
 You can also apply Pod Security Standards to multiple namespaces at once at the cluster
-level. For instructions, refer to [Apply Pod Security Standards at the cluster level](/docs/tutorials/security/cluster-level-pss).
+level. For instructions, refer to
+[Apply Pod Security Standards at the cluster level](/docs/tutorials/security/cluster-level-pss).
+
 ## {{% heading "prerequisites" %}}
 
 Install the following on your workstation:
 
 - [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
-- [kubectl](https://kubernetes.io/docs/tasks/tools/)
+- [kubectl](/docs/tasks/tools/)
 
 ## Create cluster
 
@@ -31,7 +33,9 @@ Install the following on your workstation:
    ```shell
    kind create cluster --name psa-ns-level --image kindest/node:v1.23.0
    ```
+
    The output is similar to this:
+
    ```
    Creating cluster "psa-ns-level" ...
     ✓ Ensuring node image (kindest/node:v1.23.0) 🖼 
@@ -49,10 +53,12 @@ Install the following on your workstation:
    ```
 
 1. Set the kubectl context to the new cluster:
+
    ```shell
    kubectl cluster-info --context kind-psa-ns-level
    ```
    The output is similar to this:
+
    ```
    Kubernetes control plane is running at https://127.0.0.1:50996
    CoreDNS is running at https://127.0.0.1:50996/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
@@ -67,7 +73,9 @@ Create a new namespace called `example`:
 ```shell
 kubectl create ns example
 ```
+
 The output is similar to this:
+
 ```
 namespace/example created
 ```
@@ -89,7 +97,7 @@ namespace/example created
    `warn` and `audit` for `restricted` Pod Security Standards as per the latest
    version (default value)
 
-    ```
+   ```shell
    kubectl label --overwrite ns example \
      pod-security.kubernetes.io/enforce=baseline \
      pod-security.kubernetes.io/enforce-version=latest \
@@ -117,21 +125,26 @@ namespace/example created
            - containerPort: 80
    EOF
    ```
+
 1. Apply the pod spec to the cluster in `example` namespace:
+
    ```shell
    kubectl apply -n example -f /tmp/pss/nginx-pod.yaml
    ```
    The output is similar to this:
+
    ```
    Warning: would violate PodSecurity "restricted:latest": allowPrivilegeEscalation != false (container "nginx" must set securityContext.allowPrivilegeEscalation=false), unrestricted capabilities (container "nginx" must set securityContext.capabilities.drop=["ALL"]), runAsNonRoot != true (pod or container "nginx" must set securityContext.runAsNonRoot=true), seccompProfile (pod or container "nginx" must set securityContext.seccompProfile.type to "RuntimeDefault" or "Localhost")
    pod/nginx created
    ```
 
 1. Apply the pod spec to the cluster in `default` namespace:
+
    ```shell
    kubectl apply -n default -f /tmp/pss/nginx-pod.yaml
    ```
    Output is similar to this:
+
    ```
    pod/nginx created
    ```
@@ -149,11 +162,13 @@ Run `kind delete cluster -name psa-ns-level` to delete the cluster created.
 - Run a
   [shell script](/examples/security/kind-with-namespace-level-baseline-pod-security.sh)
   to perform all the preceding steps all at once.
+
   1. Create KinD cluster
   2. Create new namespace
   3. Apply `baseline` Pod Security Standard in `enforce` mode while applying
      `restricted` Pod Security Standard also in `warn` and `audit` mode.
   4. Create a new pod with the following pod security standards applied
+
 - [Pod Security Admission](/docs/concepts/security/pod-security-admission/)
 - [Pod Security Standards](/docs/concepts/security/pod-security-standards/)
 - [Apply Pod Security Standards at the cluster level](/docs/tutorials/security/cluster-level-pss/)