Merge pull request #37594 from abrennan89/multicontainer

SRVCLI-317: Docs for kn container

Author: abrennan89

modules/serverless-kn-container.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// * serverless/cli_tools/kn-serving-ref.adoc
+// * serverless/knative_serving/serverless-applications.adoc
+
+[id="serverless-kn-container_{context}"]
+= Knative client multi-container support
+
+You can use the `kn container add` command to print YAML container spec to standard output. This command is useful for multi-container use cases because it can be used along with other standard `kn` flags to create definitions. The `kn container add` command accepts all container-related flags that are supported for use with the `kn service create` command. The `kn container add` command can also be chained by using UNIX pipes (`|`) to create multiple container definitions at once.
+
+[id="serverless-kn-container-examples_{context}"]
+== Example commands
+
+* Add a container from an image and print it to standard output:
++
+[source,terminal]
+----
+$ kn container add <container_name> --image <image_uri>
+----
++
+.Example command
+[source,terminal]
+----
+$ kn container add sidecar --image docker.io/example/sidecar
+----
++
+.Example output
+[source,terminal]
+----
+containers:
+- image: docker.io/example/sidecar
+  name: sidecar
+  resources: {}
+----
+
+* Chain two `kn container add` commands together, and then pass them to a `kn service create` command to create a Knative service with two containers:
++
+[source,terminal]
+----
+$ kn container add <first_container_name> --image <image_uri> | \
+kn container add <second_container_name> --image <image_uri> | \
+kn service create <service_name> --image <image_uri> --extra-containers -
+----
++
+`--extra-containers -` specifies a special case where `kn` reads the pipe input instead of a YAML file.
++
+.Example command
+[source,terminal]
+----
+$ kn container add sidecar --image docker.io/example/sidecar:first | \
+kn container add second --image docker.io/example/sidecar:second | \
+kn service create my-service --image docker.io/example/my-app:latest --extra-containers -
+----
++
+The `--extra-containers` flag can also accept a path to a YAML file:
++
+[source,terminal]
+----
+$ kn service create <service_name> --image <image_uri> --extra-containers <filename>
+----
++
+.Example command
+[source,terminal]
+----
+$ kn service create my-service --image docker.io/example/my-app:latest --extra-containers my-extra-containers.yaml
+----

serverless/cli_tools/kn-serving-ref.adoc

@@ -18,6 +18,16 @@ include::modules/kn-service-update.adoc[leveloffset=+2]
 include::modules/kn-service-apply.adoc[leveloffset=+2]
 include::modules/kn-service-describe.adoc[leveloffset=+2]
 
+////
+[id="kn-serving-ref-kn-container"]
+== kn container commands
+
+You can use the following commands to create and manage multiple containers in a Knative service spec.
+
+include::modules/serverless-kn-container.adoc[leveloffset=+2]
+////
+// Uncomment at 1.19.0 release
+
 [id="kn-serving-ref-domain-mapping"]
 == kn domain commands
 

serverless/knative_serving/serverless-applications.adoc

@@ -17,12 +17,19 @@ You can create a serverless application by using one of the following methods:
 * Create a Knative service using the `kn` CLI.
 * Create and apply a YAML file.
 
-=== Creating serverless applications using the Developer perspective
+[id="serverless-applications-web-console"]
+=== Creating serverless applications using the {product-title} web console
 
-For more information about creating applications using the *Developer* perspective in {product-title}, see the documentation on xref:../../applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective].
+For more information about creating applications using the *Developer* perspective in the {product-title} web console, see the documentation on xref:../../applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective].
 
 // TODO: Add admin perspective service docs
+// create service using CLI
 include::modules/creating-serverless-apps-kn.adoc[leveloffset=+2]
+
+// Uncomment at 1.19.0
+// include::modules/serverless-kn-container.adoc[leveloffset=+3]
+
+// create service using YAML
 include::modules/creating-serverless-apps-yaml.adoc[leveloffset=+2]
 
 // Update services