Merge pull request #32604 from nikhita/kubectl-subresource-support-docs

Document kubectl subresource support

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

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`