Merge pull request #71213 from bergerhoffer/OSDOCS-8476

OSDOCS#8476: Adding CLI docs for 4.15

Author: bergerhoffer

modules/oc-adm-by-example-content.adoc

@@ -149,10 +149,10 @@ Drain node in preparation for maintenance
 .Example usage
 [source,bash,options="nowrap"]
 ----
-  # Drain node "foo", even if there are pods not managed by a replication controller, replica set, job, daemon set or stateful set on it
+  # Drain node "foo", even if there are pods not managed by a replication controller, replica set, job, daemon set, or stateful set on it
   oc adm drain foo --force
 
-  # As above, but abort if there are pods not managed by a replication controller, replica set, job, daemon set or stateful set, and use a grace period of 15 minutes
+  # As above, but abort if there are pods not managed by a replication controller, replica set, job, daemon set, or stateful set, and use a grace period of 15 minutes
   oc adm drain foo --grace-period=900
 ----
 
@@ -729,6 +729,22 @@ Create a new OpenShift release
 == oc adm restart-kubelet
 Restarts kubelet on the specified nodes
 
+.Example usage
+[source,bash,options="nowrap"]
+----
+  # Restart all the nodes,  10% at a time
+  oc adm restart-kubelet nodes --all --directive=RemoveKubeletKubeconfig
+
+  # Restart all the nodes,  20 nodes at a time
+  oc adm restart-kubelet nodes --all --parallelism=20 --directive=RemoveKubeletKubeconfig
+
+  # Restart all the nodes,  15% at a time
+  oc adm restart-kubelet nodes --all --parallelism=15% --directive=RemoveKubeletKubeconfig
+
+  # Restart all the masters at the same time
+  oc adm restart-kubelet nodes -l node-role.kubernetes.io/master --parallelism=100% --directive=RemoveKubeletKubeconfig
+----
+
 
 
 == oc adm taint
@@ -747,7 +763,7 @@ Update the taints on one or more nodes
   # Remove from node 'foo' all the taints with key 'dedicated'
   oc adm taint nodes foo dedicated-
 
-  # Add a taint with key 'dedicated' on nodes having label mylabel=X
+  # Add a taint with key 'dedicated' on nodes having label myLabel=X
   oc adm taint node -l myLabel=X  dedicated=foo:PreferNoSchedule
 
   # Add to node 'foo' a taint with key 'bar' and no value
@@ -889,5 +905,12 @@ Wait for nodes to reboot after running `oc adm reboot-machine-config-pool`
 == oc adm wait-for-stable-cluster
 wait for the platform operators to become stable
 
+.Example usage
+[source,bash,options="nowrap"]
+----
+  # Wait for all clusteroperators to become stable
+  oc adm wait-for-stable-cluster
 
-
+  # Consider operators to be stable if they report as such for 5 minutes straight
+  oc adm wait-for-stable-cluster --minimum-stable-period 5m
+----

modules/oc-by-example-content.adoc

@@ -91,7 +91,7 @@ Apply a configuration to a resource by file name or stdin
   # Apply the JSON passed into stdin to a pod
   cat pod.json | oc apply -f -
 
-  # Apply the configuration from all files that end with '.json' - i.e. expand wildcard characters in file names
+  # Apply the configuration from all files that end with '.json'
   oc apply -f '*.json'
 
   # Note: --prune is still in Alpha
@@ -333,7 +333,7 @@ Output shell completion code for the specified shell (bash, zsh, fish, or powers
   ## Write bash completion code to a file and source it from .bash_profile
   oc completion bash > ~/.kube/completion.bash.inc
   printf "
-  # Kubectl shell completion
+  # oc shell completion
   source '$HOME/.kube/completion.bash.inc'
   " >> $HOME/.bash_profile
   source $HOME/.bash_profile
@@ -542,10 +542,10 @@ Set a cluster entry in kubeconfig
   # Disable cert checking for the e2e cluster entry
   oc config set-cluster e2e --insecure-skip-tls-verify=true
 
-  # Set custom TLS server name to use for validation for the e2e cluster entry
+  # Set the custom TLS server name to use for validation for the e2e cluster entry
   oc config set-cluster e2e --tls-server-name=my-cluster-name
 
-  # Set proxy url for the e2e cluster entry
+  # Set the proxy URL for the e2e cluster entry
   oc config set-cluster e2e --proxy-url=https://1.2.3.4
 ----
 
@@ -582,7 +582,7 @@ Set a user entry in kubeconfig
   # Enable the Google Compute Platform auth provider for the "cluster-admin" entry
   oc config set-credentials cluster-admin --auth-provider=gcp
 
-  # Enable the OpenID Connect auth provider for the "cluster-admin" entry with additional args
+  # Enable the OpenID Connect auth provider for the "cluster-admin" entry with additional arguments
   oc config set-credentials cluster-admin --auth-provider=oidc --auth-provider-arg=client-id=foo --auth-provider-arg=client-secret=bar
 
   # Remove the "client-secret" config value for the OpenID Connect auth provider for the "cluster-admin" entry
@@ -591,7 +591,7 @@ Set a user entry in kubeconfig
   # Enable new exec auth plugin for the "cluster-admin" entry
   oc config set-credentials cluster-admin --exec-command=/path/to/the/executable --exec-api-version=client.authentication.k8s.io/v1beta1
 
-  # Define new exec auth plugin args for the "cluster-admin" entry
+  # Define new exec auth plugin arguments for the "cluster-admin" entry
   oc config set-credentials cluster-admin --exec-arg=arg1 --exec-arg=arg2
 
   # Create or update exec auth plugin environment variables for the "cluster-admin" entry
@@ -639,7 +639,7 @@ Display merged kubeconfig settings or a specified kubeconfig file
   # Show merged kubeconfig settings
   oc config view
 
-  # Show merged kubeconfig settings and raw certificate data and exposed secrets
+  # Show merged kubeconfig settings, raw certificate data, and exposed secrets
   oc config view --raw
 
   # Get the password for the e2e user
@@ -878,7 +878,7 @@ Create an ingress with the specified name
 [source,bash,options="nowrap"]
 ----
   # Create a single ingress called 'simple' that directs requests to foo.com/bar to svc
-  # svc1:8080 with a tls secret "my-cert"
+  # svc1:8080 with a TLS secret "my-cert"
   oc create ingress simple --rule="foo.com/bar=svc1:8080,tls=my-cert"
 
   # Create a catch all ingress of "/path" pointing to service svc:port and Ingress Class as "otheringress"
@@ -1087,7 +1087,7 @@ Create a secret for use with a Docker registry
 .Example usage
 [source,bash,options="nowrap"]
 ----
-  # If you don't already have a .dockercfg file, you can create a dockercfg secret directly by using:
+  # If you do not already have a .dockercfg file, create a dockercfg secret directly
   oc create secret docker-registry my-secret --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL
 
   # Create a new secret named my-secret from ~/.docker/config.json
@@ -1216,7 +1216,7 @@ Request a service account token
   # Request a token bound to an instance of a Secret object
   oc create token myapp --bound-object-kind Secret --bound-object-name mysecret
 
-  # Request a token bound to an instance of a Secret object with a specific uid
+  # Request a token bound to an instance of a Secret object with a specific UID
   oc create token myapp --bound-object-kind Secret --bound-object-name mysecret --bound-object-uid 0d4691ed-659b-4935-a832-355f77ee47cc
 ----
 
@@ -1261,6 +1261,10 @@ Launch a new instance of a pod for debugging
   # Debug a node as an administrator
   oc debug node/master-1
 
+  # Debug a Windows Node
+  # Note: the chosen image must match the Windows Server version (2019, 2022) of the Node
+  oc debug node/win-worker-1 --image=mcr.microsoft.com/powershell:lts-nanoserver-ltsc2022
+
   # Launch a shell in a pod using the provided image stream tag
   oc debug istag/mysql:latest -n openshift
 
@@ -1294,7 +1298,7 @@ Delete resources by file names, stdin, resources and names, or by resources and
   # Delete resources from a directory containing kustomization.yaml - e.g. dir/kustomization.yaml
   oc delete -k dir
 
-  # Delete resources from all files that end with '.json' - i.e. expand wildcard characters in file names
+  # Delete resources from all files that end with '.json'
   oc delete -f '*.json'
 
   # Delete a pod based on the type and name in the JSON passed into stdin
@@ -1337,7 +1341,7 @@ Show details of a specific resource or group of resources
   oc describe pods
 
   # Describe pods by label name=myLabel
-  oc describe po -l name=myLabel
+  oc describe pods -l name=myLabel
 
   # Describe all pods managed by the 'frontend' replication controller
   # (rc-created pods get the name of the rc as a prefix in the pod name)
@@ -1379,7 +1383,7 @@ Edit a resource on the server
   # Edit the deployment 'mydeployment' in YAML and save the modified config in its annotation
   oc edit deployment/mydeployment -o yaml --save-config
 
-  # Edit the deployment/mydeployment's status subresource
+  # Edit the 'status' subresource for the 'mydeployment' deployment
   oc edit deployment mydeployment --subresource='status'
 ----
 
@@ -1391,19 +1395,19 @@ List events
 .Example usage
 [source,bash,options="nowrap"]
 ----
-  # List recent events in the default namespace.
+  # List recent events in the default namespace
   oc events
 
-  # List recent events in all namespaces.
+  # List recent events in all namespaces
   oc events --all-namespaces
 
-  # List recent events for the specified pod, then wait for more events and list them as they arrive.
+  # List recent events for the specified pod, then wait for more events and list them as they arrive
   oc events --for pod/web-pod-13je7 --watch
 
-  # List recent events in given format. Supported ones, apart from default, are json and yaml.
+  # List recent events in YAML format
   oc events -oyaml
 
-  # List recent only events in given event types
+  # List recent only events of type 'Warning' or 'Normal'
   oc events --types=Warning,Normal
 ----
 
@@ -1450,8 +1454,17 @@ Get documentation for a resource
   # Get the documentation of the resource and its fields
   oc explain pods
 
+  # Get all the fields in the resource
+  oc explain pods --recursive
+
+  # Get the explanation for deployment in supported api versions
+  oc explain deployments --api-version=apps/v1
+
   # Get the documentation of a specific field of a resource
   oc explain pods.spec.containers
+
+  # Get the documentation of resources in different format
+  oc explain deployment --output=plaintext-openapiv2
 ----
 
 
@@ -1544,12 +1557,27 @@ Display one or many resources
   # List one or more resources by their type and names
   oc get rc/web service/frontend pods/web-pod-13je7
 
-  # List status subresource for a single pod.
+  # List the 'status' subresource for a single pod
   oc get pod web-pod-13je7 --subresource status
 ----
 
 
 
+== oc get-token
+Experimental: Get token from external OIDC issuer as credentials exec plugin
+
+.Example usage
+[source,bash,options="nowrap"]
+----
+  # Starts an auth code flow to the issuer url with the client id and the given extra scopes
+  oc get-token --client-id=client-id --issuer-url=test.issuer.url --extra-scopes=email,profile
+
+  # Starts an authe code flow to the issuer url with a different callback address.
+  oc get-token --client-id=client-id --issuer-url=test.issuer.url --callback-address=127.0.0.1:8343
+----
+
+
+
 == oc idle
 Idle scalable resources
 
@@ -1728,7 +1756,7 @@ Mirror images from one repository to another
   # Note that the target registry may reject a manifest list if the platform specific images do not all
   # exist. You must use a registry with sparse registry support enabled.
   oc image mirror myregistry.com/myimage:latest=myregistry.com/other:test \
-  --filter-by-os=os/arch \
+  --filter-by-os=linux/386 \
   --keep-manifest-list=true
 ----
 
@@ -1827,6 +1855,9 @@ Log in to a server
 
   # Log in to the given server through a browser
   oc login localhost:8443 --web --callback-port 8280
+
+  # Log in to the external OIDC issuer through Auth Code + PKCE by starting a local server listening port 8080
+  oc login localhost:8443 --exec-plugin=oc-oidc --client-id=client-id --extra-scopes=email,profile --callback-port=8080
 ----
 
 
@@ -2018,7 +2049,7 @@ Update fields of a resource
   # Update a container's image using a JSON patch with positional arrays
   oc patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'
 
-  # Update a deployment's replicas through the scale subresource using a merge patch.
+  # Update a deployment's replicas through the 'scale' subresource using a merge patch
   oc patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'
 ----
 
@@ -2209,18 +2240,6 @@ Run a proxy to the Kubernetes API server
 
 
 
-== oc registry info
-Print information about the integrated registry
-
-.Example usage
-[source,bash,options="nowrap"]
-----
-  # Display information about the integrated registry
-  oc registry info
-----
-
-
-
 == oc registry login
 Log in to the integrated registry
 
@@ -2499,7 +2518,7 @@ Set a new size for a deployment, replica set, or replication controller
   oc scale --current-replicas=2 --replicas=3 deployment/mysql
 
   # Scale multiple replication controllers
-  oc scale --replicas=5 rc/foo rc/bar rc/baz
+  oc scale --replicas=5 rc/example1 rc/example2 rc/example3
 
   # Scale stateful set named 'web' to 3
   oc scale --replicas=3 statefulset/web
@@ -2981,8 +3000,8 @@ Print the client and server version information
   # Print the OpenShift client, kube-apiserver, and openshift-apiserver version information for the current context
   oc version
 
-  # Print the OpenShift client, kube-apiserver, and openshift-apiserver version numbers for the current context
-  oc version --short
+  # Print the OpenShift client, kube-apiserver, and openshift-apiserver version numbers for the current context in json format
+  oc version --output json
 
   # Print the OpenShift client version information for the current context
   oc version --client
@@ -2999,12 +3018,15 @@ Experimental: Wait for a specific condition on one or many resources
   # Wait for the pod "busybox1" to contain the status condition of type "Ready"
   oc wait --for=condition=Ready pod/busybox1
 
-  # The default value of status condition is true; you can wait for other targets after an equal delimiter (compared after Unicode simple case folding, which is a more general form of case-insensitivity):
+  # The default value of status condition is true; you can wait for other targets after an equal delimiter (compared after Unicode simple case folding, which is a more general form of case-insensitivity)
   oc wait --for=condition=Ready=false pod/busybox1
 
-  # Wait for the pod "busybox1" to contain the status phase to be "Running".
+  # Wait for the pod "busybox1" to contain the status phase to be "Running"
   oc wait --for=jsonpath='{.status.phase}'=Running pod/busybox1
 
+  # Wait for the service "loadbalancer" to have ingress.
+  oc wait --for=jsonpath='{.status.loadBalancer.ingress}' service/loadbalancer
+
   # Wait for the pod "busybox1" to be deleted, with a timeout of 60s, after having issued the "delete" command
   oc delete pod/busybox1
   oc wait --for=delete pod/busybox1 --timeout=60s
@@ -3021,5 +3043,3 @@ Return information about the current session
   # Display the currently authenticated user
   oc whoami
 ----
-
-