From 73563a3d7a989e006fdc2d8d3674c3822c5f62ce Mon Sep 17 00:00:00 2001
From: Nikhita Raghunath <nikitaraghunath@gmail.com>
Date: Mon, 4 Apr 2022 13:57:25 +0530
Subject: [PATCH] Add docs for kubectl subresource support

---
 content/en/docs/reference/kubectl/cheatsheet.md  |  6 ++++++
 content/en/docs/reference/kubectl/conventions.md | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/content/en/docs/reference/kubectl/cheatsheet.md b/content/en/docs/reference/kubectl/cheatsheet.md
index ca7e687735..a045e8223a 100644
--- a/content/en/docs/reference/kubectl/cheatsheet.md
+++ b/content/en/docs/reference/kubectl/cheatsheet.md
@@ -230,6 +230,9 @@ kubectl get pods -o json | jq -c 'paths|join(".")'
 # Produce ENV for all pods, assuming you have a default container for the pods, default namespace and the `env` command is supported.
 # Helpful when running any supported command across all pods, not just `env`
 for pod in $(kubectl get po --output=jsonpath={.items..metadata.name}); do echo $pod && kubectl exec -it $pod -- env; done
+
+# Get a deployment's status subresource
+kubectl get deployment nginx-deployment --subresource=status
 ```
 
 ## Updating resources
@@ -276,6 +279,9 @@ kubectl patch deployment valid-deployment  --type json   -p='[{"op": "remove", "
 
 # Add a new element to a positional array
 kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'
+
+# Update a deployment's replicas count by patching it's scale subresource
+kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'
 ```
 
 ## Editing resources
diff --git a/content/en/docs/reference/kubectl/conventions.md b/content/en/docs/reference/kubectl/conventions.md
index e62c5d5e44..00a842f058 100644
--- a/content/en/docs/reference/kubectl/conventions.md
+++ b/content/en/docs/reference/kubectl/conventions.md
@@ -19,6 +19,16 @@ For a stable output in a script:
 * Fully-qualify the version. For example, `jobs.v1.batch/myjob`. This will ensure that kubectl does not use its default version that can change over time.
 * Don't rely on context, preferences, or other implicit states.
 
+## Subresources
+
+* You can use the `--subresource` alpha flag for kubectl commands like `get`, `patch`,
+`edit` and `replace` to fetch and update subresources for all resources that
+support them. Currently, only the `status` and `scale` subresources are supported.
+* The API contract against a subresource is identical to a full resource. While updating the
+`status` subresource to a new value, keep in mind that the subresource could be potentially
+reconciled by a controller to a different value.
+
+
 ## Best Practices
 
 ### `kubectl run`