Skip to content

Commit 9fab681

Browse files
rh-maxrh-max
committed
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 <[email protected]> Minor markup and wording fixes
1 parent b49c630 commit 9fab681

File tree

4 files changed

+175
-1
lines changed

4 files changed

+175
-1
lines changed

‎modules/creating-serverless-apps-kn.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ The following procedure describes how you can create a basic serverless applicat
99

1010
.Prerequisites
1111
* {ServerlessOperatorName} and Knative Serving are installed on your cluster.
12-
* You have installed `kn` CLI.
12+
* You have installed the `kn` CLI.
1313

1414
.Procedure
1515

‎modules/kn-service-offline-about.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// serverless/cli_reference/kn-offline-services.adoc
4+
5+
[id="kn-service-offline-about_{context}"]
6+
= About offline mode
7+
8+
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:
9+
10+
. 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.
11+
. After the descriptor file is created, you can manually modify it and track it in a version control system.
12+
// Once `update` works, add it here and make it into a list
13+
. 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.
14+
15+
The offline mode has several uses:
16+
17+
* You can manually modify the descriptor file before using it to make changes on the cluster.
18+
* 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.
19+
* 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.
20+
21+
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.

‎modules/kn-service-offline-create.adoc‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
// Module included in the following assemblies:
2+
//
3+
// serverless/cli_reference/kn-offline-services.adoc
4+
5+
[id="creating-an-offline-service_{context}"]
6+
= Creating a service using offline mode
7+
8+
.Prerequisites
9+
10+
* {ServerlessOperatorName} and Knative Serving are installed on your cluster.
11+
* You have installed the `kn` CLI.
12+
13+
.Procedure
14+
15+
. In offline mode, create a local Knative service descriptor file:
16+
+
17+
[source,terminal]
18+
----
19+
$ kn service create event-display \
20+
--image quay.io/openshift-knative/knative-eventing-sources-event-display:latest \
21+
--target ./ \
22+
--namespace test
23+
----
24+
+
25+
.Example output
26+
[source,terminal]
27+
----
28+
Service 'event-display' created in namespace 'test'.
29+
----
30+
+
31+
* The `--target ./` flag enables offline mode and specifies `./` as the directory for storing the new directory tree.
32+
+
33+
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.
34+
+
35+
The filename can have the `.yaml`, `.yml`, or `.json` extension. Choosing `.json` creates the service descriptor file in the JSON format.
36+
+
37+
* The `--namespace test` option places the new service in the `test` namespace.
38+
+
39+
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.
40+
41+
. Examine the created directory structure:
42+
+
43+
[source,terminal]
44+
----
45+
$ tree ./
46+
----
47+
+
48+
.Example output
49+
[source,terminal]
50+
----
51+
./
52+
└── test
53+
└── ksvc
54+
└── event-display.yaml
55+
56+
2 directories, 1 file
57+
----
58+
+
59+
* The current `./` directory specified with `--target` contains the new `test/` directory that is named after the specified namespace.
60+
* The `test/` directory contains the `ksvc` directory, named after the resource type.
61+
* The `ksvc` directory contains the descriptor file `event-display.yaml`, named according to the specified service name.
62+
63+
. Examine the generated service descriptor file:
64+
+
65+
[source,terminal]
66+
----
67+
$ cat test/ksvc/event-display.yaml
68+
----
69+
+
70+
.Example output
71+
[source,yaml]
72+
----
73+
apiVersion: serving.knative.dev/v1
74+
kind: Service
75+
metadata:
76+
creationTimestamp: null
77+
name: event-display
78+
namespace: test
79+
spec:
80+
template:
81+
metadata:
82+
annotations:
83+
client.knative.dev/user-image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
84+
creationTimestamp: null
85+
spec:
86+
containers:
87+
- image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
88+
name: ""
89+
resources: {}
90+
status: {}
91+
----
92+
93+
. List information about the new service:
94+
+
95+
[source,terminal]
96+
----
97+
$ kn service describe event-display --target ./ --namespace test
98+
----
99+
+
100+
.Example output
101+
[source,terminal]
102+
----
103+
Name: event-display
104+
Namespace: test
105+
Age:
106+
URL:
107+
108+
Revisions:
109+
110+
Conditions:
111+
OK TYPE AGE REASON
112+
----
113+
114+
* The `--target ./` option specifies the root directory for the directory structure containing namespace subdirectories.
115+
+
116+
Alternatively, you can directly specify a YAML or JSON filename with the `--target` option. The accepted file extensions are `.yaml`, `.yml`, and `.json`.
117+
+
118+
* The `--namespace` option specifies the namespace, which communicates to `kn` the subdirectory that contains the necessary service descriptor file.
119+
+
120+
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.
121+
122+
. Use the service descriptor file to create the service on the cluster:
123+
+
124+
[source,terminal]
125+
----
126+
$ kn service create -f test/ksvc/event-display.yaml
127+
----
128+
+
129+
.Example output
130+
[source,terminal]
131+
----
132+
Creating service 'event-display' in namespace 'test':
133+
134+
0.058s The Route is still working to reflect the latest desired specification.
135+
0.098s ...
136+
0.168s Configuration "event-display" is waiting for a Revision to become ready.
137+
23.377s ...
138+
23.419s Ingress has not yet been reconciled.
139+
23.534s Waiting for load balancer to be ready
140+
23.723s Ready to serve.
141+
142+
Service 'event-display' created to latest revision 'event-display-00001' is available at URL:
143+
http://event-display-test.apps.example.com
144+
----

‎serverless/knative_serving/serverless-applications.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,12 @@ include::modules/kn-service-describe.adoc[leveloffset=+1]
3434

3535
include::modules/verifying-serverless-app-deployment.adoc[leveloffset=+1]
3636
include::modules/interacting-serverless-apps-http2-gRPC.adoc[leveloffset=+1]
37+
38+
[id="serverless-applications-kn-offline-mode"]
39+
== Using kn CLI in offline mode
40+
41+
:FeatureName: The offline mode of the kn CLI
42+
include::modules/technology-preview.adoc[leveloffset=+1]
43+
44+
include::modules/kn-service-offline-about.adoc[leveloffset=+2]
45+
include::modules/kn-service-offline-create.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)