1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00

SRVCOM-1728: Update structure and abstracts for CLI / ref docs

This commit is contained in:
Ashleigh Brennan
2022-04-18 12:18:31 -05:00
committed by openshift-cherrypick-robot
parent b3c2f53ad4
commit e6fecdcf50
26 changed files with 185 additions and 193 deletions

View File

@@ -481,7 +481,7 @@ Dir: updating
Distros: openshift-origin,openshift-enterprise
Topics:
- Name: Updating clusters overview
File: index
File: index
- Name: Understanding OpenShift updates
File: understanding-openshift-updates
- Name: Understanding upgrade channels
@@ -3398,9 +3398,22 @@ Topics:
File: installing-knative-eventing
- Name: Removing OpenShift Serverless
File: removing-openshift-serverless
#- Name: Get started
# File: serverless-getting-started
# uncomment once new content is added for this
# Knative kn CLI
- Name: Knative CLI
Dir: cli_tools
Topics:
- Name: Installing the Knative CLI
File: installing-kn
- Name: Configuring the Knative CLI
File: advanced-kn-config
- Name: Knative CLI plug-ins
File: kn-plugins
- Name: Knative Serving CLI commands
File: kn-serving-ref
- Name: Knative Eventing CLI commands
File: kn-eventing-ref
- Name: Functions commands
File: kn-func-ref
- Name: Develop
Dir: develop
Topics:
@@ -3530,24 +3543,3 @@ Topics:
Topics:
- Name: Using NVIDIA GPU resources with serverless applications
File: gpu-resources
# CLI tools
- Name: CLI tools
Dir: cli_tools
Topics:
- Name: Installing the Knative CLI
File: installing-kn
- Name: Knative CLI advanced configuration
File: advanced-kn-config
- Name: Reference
Dir: reference
Topics:
- Name: Knative CLI flags
File: kn-flags-reference
- Name: Knative Serving CLI commands
File: kn-serving-ref
- Name: Knative Eventing CLI commands
File: kn-eventing-ref
- Name: Functions commands
File: kn-func-ref
- Name: kn event
File: kn-event-ref

View File

@@ -242,6 +242,19 @@ Topics:
File: installing-knative-eventing
- Name: Removing OpenShift Serverless
File: removing-openshift-serverless
- Name: Knative CLI
Dir: cli_tools
Topics:
- Name: Installing the Knative CLI
File: installing-kn
- Name: Configuring the Knative CLI
File: advanced-kn-config
- Name: Knative Serving CLI commands
File: kn-serving-ref
- Name: Knative Eventing CLI commands
File: kn-eventing-ref
- Name: Functions commands
File: kn-func-ref
- Name: Develop
Dir: develop
Topics:
@@ -349,26 +362,6 @@ Topics:
File: serverless-functions-annotations
- Name: Functions development reference guide
File: serverless-functions-reference-guide
- Name: CLI tools
Dir: cli_tools
Topics:
- Name: Installing the Knative CLI
File: installing-kn
- Name: Knative CLI advanced configuration
File: advanced-kn-config
- Name: Reference
Dir: reference
Topics:
- Name: Knative CLI flags
File: kn-flags-reference
- Name: Knative Serving CLI commands
File: kn-serving-ref
- Name: Knative Eventing CLI commands
File: kn-eventing-ref
- Name: Functions commands
File: kn-func-ref
- Name: kn event
File: kn-event-ref
---
Name: Support
Dir: support

View File

@@ -1,9 +1,13 @@
:_content-type: PROCEDURE
[id="serverless-build-events-kn_{context}"]
= Building events
= Building events by using the kn-event plug-in
You can use the builder-like interface of the `kn event build` command to build an event. You can then send that event at a later time or use it in another context.
.Prerequisites
* You have installed the Knative (`kn`) CLI.
.Procedure
* Build an event:

View File

@@ -0,0 +1,53 @@
// Module included in the following assemblies:
//
// * serverless/cli_tools/installing-kn.adoc
:_content-type: PROCEDURE
[id="serverless-installing-cli-linux-rpm-package-manager_{context}"]
= Installing the Knative CLI for Linux by using an RPM package manager
For {op-system-base-full}, you can install the Knative (`kn`) CLI as an RPM by using a package manager, such as `yum` or `dnf`. This allows the Knative CLI version to be automatically managed by the system. For example, using a command like `dnf upgrade` upgrades all packages, including `kn`, if a new version is available.
.Prerequisites
* You have an active {product-title} subscription on your Red Hat account.
.Procedure
. Register with Red Hat Subscription Manager:
+
[source,terminal]
----
# subscription-manager register
----
. Pull the latest subscription data:
+
[source,terminal]
----
# subscription-manager refresh
----
. Attach the subscription to the registered system:
+
[source,terminal]
----
# subscription-manager attach --pool=<pool_id> <1>
----
+
<1> Pool ID for an active {product-title} subscription
. Enable the repositories required by the Knative (`kn`) CLI:
+
[source,terminal]
----
# subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-x86_64-rpms"
----
. Install the Knative (`kn`) CLI as an RPM by using a package manager:
+
.Example `yum` command
[source,terminal]
----
# yum install openshift-serverless-clients
----

View File

@@ -1,51 +0,0 @@
// Module included in the following assemblies:
//
// * serverless/cli_tools/installing-kn.adoc
:_content-type: PROCEDURE
[id="installing-cli-linux-rpm_{context}"]
= Installing the Knative CLI for Linux using an RPM
For {op-system-base-full}, you can install the `kn` CLI as an RPM if you have an active {product-title} subscription on your Red Hat account.
// no prereqs?
.Procedure
// better explanation of what each of these commands do?
. Enter the command:
+
[source,terminal]
----
# subscription-manager register
----
. Enter the command:
+
[source,terminal]
----
# subscription-manager refresh
----
. Enter the command:
+
[source,terminal]
----
# subscription-manager attach --pool=<pool_id> <1>
----
+
<1> Pool ID for an active {product-title} subscription
. Enter the command:
+
[source,terminal]
----
# subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-x86_64-rpms"
----
. Enter the command:
+
[source,terminal]
----
# yum install openshift-serverless-clients
----

View File

@@ -6,19 +6,31 @@
[id="installing-cli-linux_{context}"]
= Installing the Knative CLI for Linux
For Linux distributions, you can download the `kn` CLI directly as a `tar.gz` archive.
If you are using a Linux distribution that does not have RPM or another package manager installed, you can install the Knative (`kn`) CLI as a binary file. To do this, you must download and unpack a `tar.gz` archive and add the binary to a directory on your `PATH`.
// no prereqs?
.Prerequisites
* If you are not using RHEL or Fedora, ensure that *libc* is installed in a directory on your library path.
+
[IMPORTANT]
====
If *libc* is not available, you might see the following error when you run CLI commands:
[source,terminal]
----
$ kn: No such file or directory
----
====
.Procedure
. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-linux-amd64.tar.gz[`kn` CLI].
. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-linux-amd64.tar.gz[Knative (`kn`) CLI `tar.gz` archive].
. Unpack the archive:
+
[source,terminal]
----
$ tar -xf <file>
$ tar -xf <filename>
----
. Move the `kn` binary to a directory on your `PATH`.
@@ -29,14 +41,3 @@ $ tar -xf <file>
----
$ echo $PATH
----
+
[NOTE]
====
If you do not use RHEL or Fedora, ensure that *libc* is installed in a directory on your library path.
If *libc* is not available, you might see the following error when you run CLI commands:
[source,terminal]
----
$ kn: No such file or directory
----
====

View File

@@ -3,18 +3,18 @@
// * serverless/cli_tools/installing-kn.adoc
:_content-type: PROCEDURE
[id="installing-cli-macosx_{context}"]
[id="serverless-installing-cli-macos_{context}"]
= Installing the Knative CLI for macOS
The `kn` CLI for macOS is provided as a `tar.gz` archive.
If you are using macOS, you can install the Knative (`kn`) CLI as a binary file. To do this, you must download and unpack a `tar.gz` archive and add the binary to a directory on your `PATH`.
// no prereqs?
.Procedure
. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-macos-amd64.tar.gz[`kn` CLI].
. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-macos-amd64.tar.gz[Knative (`kn`) CLI `tar.gz` archive].
. Unpack and unzip the archive.
. Unpack and extract the archive.
. Move the `kn` binary to a directory on your `PATH`.

View File

@@ -6,12 +6,22 @@
[id="installing-cli-web-console_{context}"]
= Installing the Knative CLI using the {product-title} web console
You can use the following procedure to install the `kn` CLI by using the web console.
Using the {product-title} web console provides a streamlined and intuitive user interface to install the Knative (`kn`) CLI. After the {ServerlessOperatorName} is installed, you will see a link to download the Knative (`kn`) CLI for Linux (amd64, s390x, ppc64le), macOS, or Windows from the *Command Line Tools* page in the {product-title} web console.
.Prerequisites
* You have logged in to the {product-title} web console.
* The {ServerlessOperatorName} is installed on your {product-title} cluster. After the {ServerlessOperatorName} is installed, you will see a link to download the Knative CLI (`kn`) for Linux (x86_64, amd64, s390x, ppc64le), macOS, or Windows from the *Command Line Tools* page in the {product-title} web console.
* The {ServerlessOperatorName} is installed on your {product-title} cluster.
+
[IMPORTANT]
====
If *libc* is not available, you might see the following error when you run CLI commands:
[source,terminal]
----
$ kn: No such file or directory
----
====
.Procedure
@@ -23,22 +33,12 @@ You can use the following procedure to install the `kn` CLI by using the web con
----
$ tar -xf <file>
----
. Move the `kn` binary to a directory on your `PATH`.
. To check your `PATH`, run:
+
[source,terminal]
----
$ echo $PATH
----
+
[NOTE]
====
If you do not use RHEL or Fedora, ensure that *libc* is installed in a directory on your library path.
If *libc* is not available, you might see the following error when you run CLI commands:
[source,terminal]
----
$ kn: No such file or directory
----
====

View File

@@ -6,13 +6,13 @@
[id="installing-cli-windows_{context}"]
= Installing the Knative CLI for Windows
The `kn` CLI for Windows is provided as a zip archive.
If you are using Windows, you can install the Knative (`kn`) CLI as a binary file. To do this, you must download and unpack a ZIP archive and add the binary to a directory on your `PATH`.
// no prereqs?
.Procedure
. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-windows-amd64.zip[`kn` CLI].
. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-windows-amd64.zip[Knative (`kn`) CLI ZIP archive].
. Extract the archive with a ZIP program.

View File

@@ -1,11 +0,0 @@
// Module included in the following assemblies:
//
// * serverless/cli_tools/advanced-kn-config.adoc
:_content-type: CONCEPT
[id="serverless-kn-plugins_{context}"]
= Knative CLI plug-ins
The `kn` CLI supports the use of plug-ins, which enable you to extend the functionality of your `kn` installation by adding custom commands and other shared commands that are not part of the core distribution. `kn` CLI plug-ins are used in the same way as the main `kn` functionality.
Currently, Red Hat supports the `kn-source-kafka` plug-in.

View File

@@ -1,9 +1,13 @@
:_content-type: PROCEDURE
[id="serverless-send-events-kn_{context}"]
= Sending events
= Sending events by using the kn-event plug-in
You can use the `kn event send` command to send an event. The events can be sent either to publicly available addresses or to addressable resources inside a cluster, such as Kubernetes services, as well as Knative services, brokers, and channels. The command uses the same builder-like interface as the `kn event build` command.
.Prerequisites
* You have installed the Knative (`kn`) CLI.
.Procedure
* Send an event:

View File

@@ -1,12 +1,38 @@
:_content-type: ASSEMBLY
[id="advanced-kn-config"]
= Knative CLI advanced configuration
= Configuring the Knative CLI
:context: advanced-kn-config
include::_attributes/common-attributes.adoc[]
toc::[]
You can customize and extend the `kn` CLI by using advanced features, such as configuring a `config.yaml` file for `kn` or using plug-ins.
You can customize your Knative (`kn`) CLI setup by creating a `config.yaml` configuration file. You can provide this configuration by using the `--config` flag, otherwise the configuration is picked up from a default location. The default configuration location conforms to the https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification], and is different for UNIX systems and Windows systems.
include::modules/serverless-kn-config.adoc[leveloffset=+1]
include::modules/serverless-kn-cli-plugins.adoc[leveloffset=+1]
For UNIX systems:
* If the `XDG_CONFIG_HOME` environment variable is set, the default configuration location that the Knative (`kn`) CLI looks for is `$XDG_CONFIG_HOME/kn`.
* If the `XDG_CONFIG_HOME` environment variable is not set, the Knative (`kn`) CLI looks for the configuration in the home directory of the user at `$HOME/.config/kn/config.yaml`.
For Windows systems, the default Knative (`kn`) CLI configuration location is `%APPDATA%\kn`.
.Example configuration file
[source,yaml]
----
plugins:
path-lookup: true <1>
directory: ~/.config/kn/plugins <2>
eventing:
sink-mappings: <3>
- prefix: svc <4>
group: core <5>
version: v1 <6>
resource: services <7>
----
<1> Specifies whether the Knative (`kn`) CLI should look for plug-ins in the `PATH` environment variable. This is a boolean configuration option. The default value is `false`.
<2> Specifies the directory where the Knative (`kn`) CLI looks for plug-ins. The default path depends on the operating system, as described previously. This can be any directory that is visible to the user.
<3> The `sink-mappings` spec defines the Kubernetes addressable resource that is used when you use the `--sink` flag with a Knative (`kn`) CLI command.
<4> The prefix you want to use to describe your sink. `svc` for a service, `channel`, and `broker` are predefined prefixes for the Knative (`kn`) CLI.
<5> The API group of the Kubernetes resource.
<6> The version of the Kubernetes resource.
<7> The plural name of the Kubernetes resource type. For example, `services` or `brokers`.

View File

@@ -6,17 +6,15 @@ include::_attributes/common-attributes.adoc[]
toc::[]
Installation options for the `oc` CLI may vary depending on your operating system.
The Knative CLI (`kn`) does not have its own login mechanism. To log in to the cluster, you must install the `oc` CLI and use the `oc login` command.
The Knative (`kn`) CLI does not have its own login mechanism. To log in to the cluster, you must install the OpenShift (`oc`) CLI and use the `oc login` command. Installation options for the CLIs may vary depending on your operating system.
ifdef::openshift-enterprise[]
For more information on installing the `oc` CLI for your operating system and logging in with `oc`, see the xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[OpenShift CLI getting started] documentation.
For more information on installing the OpenShift (`oc`) CLI for your operating system and logging in with `oc`, see the xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[OpenShift CLI getting started] documentation.
endif::[]
// need to wait til CLI docs are added to OSD for this link to work
// TODO: remove this conditional once this is available
{ServerlessProductName} cannot be installed using the `kn` CLI. A cluster administrator must install the {ServerlessOperatorName} and set up the Knative components, as described in the xref:../../serverless/install/install-serverless-operator.adoc#install-serverless-operator[Installing the {ServerlessOperatorName}] documentation.
{ServerlessProductName} cannot be installed using the Knative (`kn`) CLI. A cluster administrator must install the {ServerlessOperatorName} and set up the Knative components, as described in the xref:../../serverless/install/install-serverless-operator.adoc#install-serverless-operator[Installing the {ServerlessOperatorName}] documentation.
[IMPORTANT]
====
@@ -26,9 +24,10 @@ For example, if you use the 1.16.0 release of the `kn` CLI, which uses version 0
Ensure that you are using the latest `kn` CLI version for your {ServerlessProductName} release to avoid issues.
====
// need to update this note, out of scope for this PR
include::modules/serverless-installing-cli-web-console.adoc[leveloffset=+1]
include::modules/serverless-installing-cli-linux-rpm.adoc[leveloffset=+1]
include::modules/serverless-installing-cli-linux-rpm-package-manager.adoc[leveloffset=+1]
include::modules/serverless-installing-cli-linux.adoc[leveloffset=+1]
include::modules/serverless-installing-cli-linux-ibm-power-rpm.adoc[leveloffset=+1]
include::modules/serverless-installing-cli-linux-ibm-power-tarball.adoc[leveloffset=+1]

View File

@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
toc::[]
You can use the following `kn` CLI commands to complete Knative Eventing tasks on the cluster.
You can use the following Knative (`kn`) CLI commands to complete Knative Eventing tasks on the cluster.
[id="kn-eventing-ref-kn-sources"]
== kn source commands
@@ -14,6 +14,7 @@ You can use the following `kn` CLI commands to complete Knative Eventing tasks o
You can use the following commands to list, create, and manage Knative event sources.
include::modules/serverless-list-source-types-kn.adoc[leveloffset=+2]
include::modules/specifying-sink-flag-kn.adoc[leveloffset=+2]
include::modules/serverless-kn-containersource.adoc[leveloffset=+2]
include::modules/apiserversource-kn.adoc[leveloffset=+2]
include::modules/serverless-pingsource-kn.adoc[leveloffset=+2]

View File

@@ -0,0 +1,17 @@
:_content-type: ASSEMBLY
[id="kn-plugins"]
= Knative CLI plug-ins
include::_attributes/common-attributes.adoc[]
:context: kn-plugins
toc::[]
The Knative (`kn`) CLI supports the use of plug-ins, which enable you to extend the functionality of your `kn` installation by adding custom commands and other shared commands that are not part of the core distribution. Knative (`kn`) CLI plug-ins are used in the same way as the main `kn` functionality.
Currently, Red Hat supports the `kn-source-kafka` plug-in and the `kn-event` plug-in.
:FeatureName: The `kn-event` plug-in
include::snippets/technology-preview.adoc[leveloffset=+1]
// kn event commands
include::modules/serverless-build-events-kn.adoc[leveloffset=+1]
include::modules/serverless-send-events-kn.adoc[leveloffset=+1]

View File

@@ -66,5 +66,5 @@ include::modules/serverless-https-redirect-service.adoc[leveloffset=+1]
[id="additional-resources_serverless-applications"]
[role="_additional-resources"]
== Additional resources
* xref:../../serverless/reference/kn-serving-ref.adoc#kn-serving-ref[Knative Serving CLI commands]
* xref:../../serverless/cli_tools/kn-serving-ref.adoc#kn-serving-ref[Knative Serving CLI commands]
* xref:../../serverless/security/serverless-ossm-with-kourier-jwt.adoc#serverless-ossm-with-kourier-jwt[Configuring JSON Web Token authentication for Knative services]

View File

@@ -17,7 +17,7 @@ include::modules/specifying-sink-flag-kn.adoc[leveloffset=+1]
[TIP]
====
You can configure which CRs can be used with the `--sink` flag for `kn` CLI commands by xref:../../serverless/cli_tools/advanced-kn-config.adoc#serverless-kn-config_advanced-kn-config[Customizing `kn`].
You can configure which CRs can be used with the `--sink` flag for `kn` CLI commands by xref:../../serverless/cli_tools/advanced-kn-config.adoc#advanced-kn-config[Customizing `kn`].
====
// Connect sinks to sources in ODC

View File

@@ -1 +0,0 @@
../../_attributes/

View File

@@ -1 +0,0 @@
../images

View File

@@ -1,14 +0,0 @@
[id="kn-event-ref"]
= kn event
include::_attributes/common-attributes.adoc[]
:context: kn-event-ref
toc::[]
:FeatureName: The `kn event` plug-in
include::snippets/technology-preview.adoc[leveloffset=+2]
You can use the `kn event` set of commands to manage cloud events from the command line.
include::modules/serverless-build-events-kn.adoc[leveloffset=+1]
include::modules/serverless-send-events-kn.adoc[leveloffset=+1]

View File

@@ -1,11 +0,0 @@
:_content-type: ASSEMBLY
[id="kn-flags-reference"]
= Knative CLI flags
include::_attributes/common-attributes.adoc[]
:context: kn-flags-reference
toc::[]
This section provides information about additional, optional flags that you can use with `kn` commands.
include::modules/specifying-sink-flag-kn.adoc[leveloffset=+1]

View File

@@ -1 +0,0 @@
../modules

View File

@@ -1 +0,0 @@
../../snippets

View File

@@ -1,7 +0,0 @@
:_content-type: ASSEMBLY
include::_attributes/common-attributes.adoc[]
[id="serverless-getting-started"]
= Getting started with {ServerlessProductName}
:context: serverless-getting-started
toc::[]