From 514b81f5f8108648cfe2f70079e65332fc778ea0 Mon Sep 17 00:00:00 2001 From: Maxim Svistunov Date: Thu, 20 May 2021 15:43:48 +0200 Subject: [PATCH] Add docs on using offline services with the kn CLI Add Technology Preview note for using offline services Improve feature name in TP note Move Using offline services to serverless/knative_serving Fix section nesting level Numerous improvements Add missing output line Numerous stylistic improvements s/the offline mode/offline mode/ Lowercase "Continuous Integration" Co-authored-by: Ashleigh Brennan Minor markup and wording fixes --- modules/creating-serverless-apps-kn.adoc | 2 +- modules/kn-service-offline-about.adoc | 21 +++ modules/kn-service-offline-create.adoc | 144 ++++++++++++++++++ .../serverless-applications.adoc | 9 ++ 4 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 modules/kn-service-offline-about.adoc create mode 100644 modules/kn-service-offline-create.adoc diff --git a/modules/creating-serverless-apps-kn.adoc b/modules/creating-serverless-apps-kn.adoc index c33c91343c..ba84f2d469 100644 --- a/modules/creating-serverless-apps-kn.adoc +++ b/modules/creating-serverless-apps-kn.adoc @@ -9,7 +9,7 @@ The following procedure describes how you can create a basic serverless applicat .Prerequisites * {ServerlessOperatorName} and Knative Serving are installed on your cluster. -* You have installed `kn` CLI. +* You have installed the `kn` CLI. .Procedure diff --git a/modules/kn-service-offline-about.adoc b/modules/kn-service-offline-about.adoc new file mode 100644 index 0000000000..5d96d48704 --- /dev/null +++ b/modules/kn-service-offline-about.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// serverless/cli_reference/kn-offline-services.adoc + +[id="kn-service-offline-about_{context}"] += About offline mode + +Normally, when you execute `kn service` commands, the changes immediately propagate to the cluster. However, as an alternative, you can execute `kn service` commands in offline mode: + +. When you create a service in offline mode, no changes happen on the cluster. Instead, the only thing that happens is the creation of the service descriptor file on your local machine. +. After the descriptor file is created, you can manually modify it and track it in a version control system. +// Once `update` works, add it here and make it into a list +. Finally, you can propagate changes to the cluster by using the `kn service create -f`, `kn service apply -f`, or `oc apply -f` commands on the descriptor files. + +The offline mode has several uses: + +* You can manually modify the descriptor file before using it to make changes on the cluster. +* You can locally track the descriptor file of a service in a version control system. This enables you to reuse the descriptor file in places other than the target cluster, for example in continuous integration (CI) pipelines, development environments, or demos. +* You can examine the created descriptor files to learn about Knative services. In particular, you can see how the resulting service is influenced by the different arguments passed to the `kn` command. + +The offline mode has its advantages: it is fast, and does not require a connection to the cluster. However, offline mode lacks server-side validation. Consequently, you cannot, for example, verify that the service name is unique or that the specified image can be pulled. diff --git a/modules/kn-service-offline-create.adoc b/modules/kn-service-offline-create.adoc new file mode 100644 index 0000000000..4d77473771 --- /dev/null +++ b/modules/kn-service-offline-create.adoc @@ -0,0 +1,144 @@ +// Module included in the following assemblies: +// +// serverless/cli_reference/kn-offline-services.adoc + +[id="creating-an-offline-service_{context}"] += Creating a service using offline mode + +.Prerequisites + +* {ServerlessOperatorName} and Knative Serving are installed on your cluster. +* You have installed the `kn` CLI. + +.Procedure + +. In offline mode, create a local Knative service descriptor file: ++ +[source,terminal] +---- +$ kn service create event-display \ + --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest \ + --target ./ \ + --namespace test +---- ++ +.Example output +[source,terminal] +---- +Service 'event-display' created in namespace 'test'. +---- ++ +* The `--target ./` flag enables offline mode and specifies `./` as the directory for storing the new directory tree. ++ +If you do not specify an existing directory, but use a filename, such as `--target my-service.yaml`, then no directory tree is created. Instead, only the service descriptor file `my-service.yaml` is created in the current directory. ++ +The filename can have the `.yaml`, `.yml`, or `.json` extension. Choosing `.json` creates the service descriptor file in the JSON format. ++ +* The `--namespace test` option places the new service in the `test` namespace. ++ +If you do not use `--namespace`, and you are logged in to an OpenShift cluster, the descriptor file is created in the current namespace. Otherwise, the descriptor file is created in the `default` namespace. + +. Examine the created directory structure: ++ +[source,terminal] +---- +$ tree ./ +---- ++ +.Example output +[source,terminal] +---- +./ +└── test + └── ksvc + └── event-display.yaml + +2 directories, 1 file +---- ++ +* The current `./` directory specified with `--target` contains the new `test/` directory that is named after the specified namespace. +* The `test/` directory contains the `ksvc` directory, named after the resource type. +* The `ksvc` directory contains the descriptor file `event-display.yaml`, named according to the specified service name. + +. Examine the generated service descriptor file: ++ +[source,terminal] +---- +$ cat test/ksvc/event-display.yaml +---- ++ +.Example output +[source,yaml] +---- +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + creationTimestamp: null + name: event-display + namespace: test +spec: + template: + metadata: + annotations: + client.knative.dev/user-image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest + creationTimestamp: null + spec: + containers: + - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest + name: "" + resources: {} +status: {} +---- + +. List information about the new service: ++ +[source,terminal] +---- +$ kn service describe event-display --target ./ --namespace test +---- ++ +.Example output +[source,terminal] +---- +Name: event-display +Namespace: test +Age: +URL: + +Revisions: + +Conditions: + OK TYPE AGE REASON +---- + +* The `--target ./` option specifies the root directory for the directory structure containing namespace subdirectories. ++ +Alternatively, you can directly specify a YAML or JSON filename with the `--target` option. The accepted file extensions are `.yaml`, `.yml`, and `.json`. ++ +* The `--namespace` option specifies the namespace, which communicates to `kn` the subdirectory that contains the necessary service descriptor file. ++ +If you do not use `--namespace`, and you are logged in to an OpenShift cluster, `kn` searches for the service in the subdirectory that is named after the current namespace. Otherwise, `kn` searches in the `default/` subdirectory. + +. Use the service descriptor file to create the service on the cluster: ++ +[source,terminal] +---- +$ kn service create -f test/ksvc/event-display.yaml +---- ++ +.Example output +[source,terminal] +---- +Creating service 'event-display' in namespace 'test': + + 0.058s The Route is still working to reflect the latest desired specification. + 0.098s ... + 0.168s Configuration "event-display" is waiting for a Revision to become ready. + 23.377s ... + 23.419s Ingress has not yet been reconciled. + 23.534s Waiting for load balancer to be ready + 23.723s Ready to serve. + +Service 'event-display' created to latest revision 'event-display-00001' is available at URL: +http://event-display-test.apps.example.com +---- diff --git a/serverless/knative_serving/serverless-applications.adoc b/serverless/knative_serving/serverless-applications.adoc index c0c1125276..00b532b5da 100644 --- a/serverless/knative_serving/serverless-applications.adoc +++ b/serverless/knative_serving/serverless-applications.adoc @@ -34,3 +34,12 @@ include::modules/kn-service-describe.adoc[leveloffset=+1] include::modules/verifying-serverless-app-deployment.adoc[leveloffset=+1] include::modules/interacting-serverless-apps-http2-gRPC.adoc[leveloffset=+1] + +[id="serverless-applications-kn-offline-mode"] +== Using kn CLI in offline mode + +:FeatureName: The offline mode of the kn CLI +include::modules/technology-preview.adoc[leveloffset=+1] + +include::modules/kn-service-offline-about.adoc[leveloffset=+2] +include::modules/kn-service-offline-create.adoc[leveloffset=+2]