Skip to content

Commit 8bb983a

Browse files
abrennan89abrennan89
authored
Merge pull request #32671 from rh-max/srvls-offline-services
SRVCLI-259: Add docs on using offline services with the kn CLI
2 parents ab03a27 + 9fab681 commit 8bb983a

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)