starlingx/docs
Code Issues Proposed changes

Change User Tasks

Browse Source 
Signed-off-by: Rafael Jardim <rafaeljordao.jardim@windriver.com>
Change-Id: Ifb4fa92be9aaad2a9a78980fc6e922dd56ab3423
This commit is contained in:
Rafael Jardim 2021-03-05 15:22:09 -03:00
parent 8ff2e4acee
commit c7da34243b
16 changed files with 263 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
doc/source/_includes/kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients.rest Normal file
View File

1
doc/source/shared/abbrevs.txt
View File

@ -20,6 +20,7 @@
.. |CAs| replace:: :abbr:`CAs (Certificate Authorities)`
.. |CLI| replace:: :abbr:`CLI (Command Line Interface)`
.. |CMK| replace:: :abbr:`CMK (CPU Manager for Kubernetes)`
.. |CLIs| replace:: :abbr:`CLIs (Command Line Interfaces)`
.. |CNI| replace:: :abbr:`CNI (Container Networking Interface)`
.. |CoW| replace:: :abbr:`CoW (Copy on Write)`
.. |CSK| replace:: :abbr:`CSK (Code Signing Key)`

1
doc/source/usertasks/index.rs1
View File

@ -9,6 +9,7 @@
- :ref:`Remote CLI Access <remote-cli-access>`
- :ref:`Configuring Container-backed Remote CLIs and Clients <kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients>`
- :ref:`Using Container-backed Remote CLIs and Clients <using-container-based-remote-clis-and-clients>`
- :ref:`Installing Kubectl and Helm Clients Directly on a Host <kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host>`
- :ref:`Configuring Remote Helm Client <configuring-remote-helm-client>`

2
doc/source/usertasks/kubernetes/configuring-remote-helm-client.rst
View File

@ -88,7 +88,7 @@ commands can be run by the non-admin user, locally or remotely.
~(keystone_admin)]$ helm init --service-account=tiller --tiller-namespace=$NAMESPACE --output yaml | sed 's@apiVersion: extensions/v1beta1@apiVersion: apps/v1@' | sed 's@ replicas: 1@ replicas: 1\n \ selector: {"matchLabels": {"app": "helm", "name": "tiller"}}@' > helm-init.yaml
~(keystone_admin)]$ kubectl apply -f helm-init.yaml
~(keystone_admin)]$ helm init –client-only
~(keystone_admin)]$ helm init --client-only --home "./.helm"
.. note::
Ensure that each of the patterns between single quotes in the above

6
doc/source/usertasks/kubernetes/creating-network-attachment-definitions.rst
View File

@ -39,7 +39,7 @@ this data network.
.. code-block:: yaml
~(keystone_admin)$ cat <<EOF > net1.yaml
~(keystone_admin)]$ cat <<EOF > net1.yaml
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
@ -65,7 +65,7 @@ this data network.
.. code-block:: none
~(keystone_admin)$ cat <<EOF > net2.yaml
~(keystone_admin)]$ cat <<EOF > net2.yaml
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
@ -85,7 +85,7 @@ this data network.
.. code-block:: none
~(keystone_admin)$ cat <<EOF > net3.yaml
~(keystone_admin)]$ cat <<EOF > net3.yaml
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:

1
doc/source/usertasks/kubernetes/index.rst
View File

@ -22,6 +22,7 @@ Remote CLI access
usertask-using-container-backed-remote-clis-and-clients
kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host
configuring-remote-helm-client
using-container-based-remote-clis-and-clients
GUI access
**********

31
doc/source/usertasks/kubernetes/kubernetes-user-tutorials-authentication-and-authorization.rst
View File

@ -15,16 +15,29 @@ For example:
$ docker login registry.local:9001 -u <keystoneUserName> -p <keystonePassword>
An authorized administrator can perform any docker action, while regular users
can only interact with their own repositories \(i.e.
``registry.local:9001/<keystoneUserName>/``\). For example, only **admin** and
**testuser** accounts can push to or pull from:
An authorized administrator \('admin' and 'sysinv'\) can perform any docker
action. Regular users can only interact with their own repositories \(i.e.
``registry.local:9001/<keystoneUserName>/``\). Any authenticated user can pull
from the following list of public images:
.. _kubernetes-user-tutorials-authentication-and-authorization-d315e50:
- registry.local:9001:/public/\*
- registry.local:9001:/k8s.gcr.io/pause
- registry.local:9001:/quay.io/jetstack/cert-manager-acmesolver
The **mtce** user can only pull public images, but cannot push any images.
For example, only **admin** and **testuser** accounts can push to or pull from:
.. code-block:: none
registry.local:9001/testuser/busybox:latest
.. _kubernetes-user-tutorials-authentication-and-authorization-d315e59:
.. _kubernetes-user-tutorials-authentication-and-authorization-d315e87:
---------------------------------
Username and Docker Compatibility
@ -39,6 +52,14 @@ example, the user **testuser** is correct in the following URL, while
registry.local:9001/testuser/busybox:latest
.. note::
Use of the auto-generated self-signed certificate for the registry
certificate is not recommended. If you must do so, then from the central
cloud/systemController, access to the local registry can only be done using
registry.local:9001. registry.central:9001 will be inaccessible. Installing
a CA-signed certificate for the registry and the certificate of the CA as
an 'ssl\_ca' certificate will remove this restriction.
.. seealso::
`https://docs.docker.com/engine/reference/commandline/docker/
<https://docs.docker.com/engine/reference/commandline/docker/>`__ for more

69
doc/source/usertasks/kubernetes/kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients.rst
View File

@ -12,9 +12,8 @@ Linux, MacOS, and Windows.
.. rubric:: |context|
This functionality is made available using a docker container with
pre-installed :abbr:`CLIs (Command Line Interfaces)` and clients. The
container's image is pulled as required by the remote CLI/client configuration
scripts.
pre-installed |CLIs| and clients. The container's image is pulled as required
by the remote CLI/client configuration scripts.
.. rubric:: |prereq|
@ -51,7 +50,7 @@ scripts.
- You will need a kubectl config file containing your user account and login
credentials from your |prod| administrator.
The following procedure helps you configure the Container-backed remote CLIs
The following procedure helps you configure the Container-backed remote |CLIs|
and clients for a non-admin user.
.. rubric:: |proc|
@ -106,7 +105,7 @@ and clients for a non-admin user.
$ cd $HOME/|prefix|-remote-clients-<version>/
#. Create a working directory that will be mounted by the container
implementing the remote CLIs.
implementing the remote |CLIs|.
See the description of the :command:`configure\_client.sh` ``-w`` option
:ref:`below <kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients-w-option>` for more details.
@ -117,28 +116,38 @@ and clients for a non-admin user.
#. Run the :command:`configure\_client.sh` script.
.. code-block:: none
.. only:: starlingx
$ ./configure_client.sh -t platform -r my_openrc.sh -k user-kubeconfig -w $HOME/remote_cli_wd
.. code-block:: none
where the options for configure\_client.sh are:
$ ./configure_client.sh -t platform -r my_openrc.sh -k user-kubeconfig -w $HOME/remote_cli_wd
.. only:: partner
.. include:: ../../_includes/kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients.rest
If you specify repositories that require authentication, as shown
above, you must remember to perform a :command:`docker login` to
that repository before using remote |CLIs| for the first time.
The options for configure\_client.sh are:
**-t**
The type of client configuration. The options are platform \(for
|prod-long| CLI and clients\) and openstack \(for |prod-os|
application CLI and clients\).
|prod-long| |CLI| and clients\) and openstack \(for |prod-os|
application |CLI| and clients\).
The default value is platform.
**-r**
The user/tenant RC file to use for :command:`openstack` CLI
The user/tenant RC file to use for :command:`openstack` |CLI|
commands.
The default value is admin-openrc.sh.
**-k**
The kubernetes configuration file to use for :command:`kubectl` and
:command:`helm` CLI commands.
:command:`helm` |CLI| commands.
The default value is temp-kubeconfig.
@ -146,7 +155,7 @@ and clients for a non-admin user.
The remote CLI/client RC file generated by this script.
This RC file needs to be sourced in the shell to set up required
environment variables and aliases before running any remote CLI
environment variables and aliases before running any remote |CLI|
commands.
For the platform client setup, the default is
@ -157,17 +166,17 @@ and clients for a non-admin user.
**-w**
The working directory that will be mounted by the container
implementing the remote CLIs. When using the remote CLIs, any files
passed as arguments to the remote CLI commands need to be in this
implementing the remote |CLIs|. When using the remote |CLIs|, any files
passed as arguments to the remote |CLI| commands need to be in this
directory in order for the container to access the files. The
default value is the directory from which the
:command:`configure\_client.sh` command was run.
**-p**
Override the container image for the platform CLI and clients.
Override the container image for the platform |CLI| and clients.
By default, the platform CLIs and clients container image is pulled
from docker.io/starlingx/stx-platformclients.
By default, the platform |CLIs| and clients container image is
pulled from docker.io/starlingx/stx-platformclients.
For example, to use the container images from the WRS AWS ECR:
@ -177,28 +186,40 @@ and clients for a non-admin user.
If you specify repositories that require authentication, you must
perform a :command:`docker login` to that repository before using
remote CLIs.
remote |CLIs|.
**-a**
Override the OpenStack application image.
By default, the OpenStack CLIs and clients container image is
By default, the OpenStack |CLIs| and clients container image is
pulled from docker.io/starlingx/stx-openstackclients.
The :command:`configure-client.sh` command will generate a
remote\_client\_platform.sh RC file. This RC file needs to be sourced
in the shell to set up required environment variables and aliases
before any remote CLI commands can be run.
before any remote |CLI| commands can be run.
.. rubric:: |postreq|
After configuring the platform's container-backed remote CLIs/clients, the
remote platform CLIs can be used in any shell after sourcing the generated
remote platform |CLIs| can be used in any shell after sourcing the generated
remote CLI/client RC file. This RC file sets up the required environment
variables and aliases for the remote CLI commands.
variables and aliases for the remote |CLI| commands.
.. note::
Consider adding this command to your .login or shell rc file, such that
your shells will automatically be initialized with the environment
variables and aliases for the remote CLI commands.
variables and aliases for the remote |CLI| commands.
See :ref:`Using Container-backed Remote CLIs and Clients <using-container-based-remote-clis-and-clients>` for details.
**Related information**
.. seealso::
:ref:`Using Container-backed Remote CLIs and Clients
<using-container-based-remote-clis-and-clients>`
:ref:`Installing Kubectl and Helm Clients Directly on a Host
<kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host>`
:ref:`Configuring Remote Helm Client <configuring-remote-helm-client>`

12
doc/source/usertasks/kubernetes/kubernetes-user-tutorials-creating-persistent-volume-claims.rst
View File

@ -17,7 +17,7 @@ The following steps create two 1Gb persistent volume claims.
.. rubric:: |proc|
.. _kubernetes-user-tutorials-creating-persistent-volume-claims-d385e32:
.. _kubernetes-user-tutorials-creating-persistent-volume-claims-d395e32:
#. Create the **test-claim1** persistent volume claim.
@ -28,7 +28,7 @@ The following steps create two 1Gb persistent volume claims.
.. code-block:: yaml
~(keystone_admin)$ cat <<EOF > claim1.yaml
~(keystone_admin)]$ cat <<EOF > claim1.yaml
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
@ -46,7 +46,7 @@ The following steps create two 1Gb persistent volume claims.
.. code-block:: none
~(keystone_admin)$ kubectl apply -f claim1.yaml
~(keystone_admin)]$ kubectl apply -f claim1.yaml
persistentvolumeclaim/test-claim1 created
#. Create the **test-claim2** persistent volume claim.
@ -57,7 +57,7 @@ The following steps create two 1Gb persistent volume claims.
.. code-block:: yaml
~(keystone_admin)$ cat <<EOF > claim2.yaml
~(keystone_admin)]$ cat <<EOF > claim2.yaml
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
@ -75,7 +75,7 @@ The following steps create two 1Gb persistent volume claims.
.. code-block:: none
~(keystone_admin)$ kubectl apply -f claim2.yaml
~(keystone_admin)]$ kubectl apply -f claim2.yaml
persistentvolumeclaim/test-claim2 created
.. rubric:: |result|
@ -85,7 +85,7 @@ following command.
.. code-block:: none
~(keystone_admin)$ kubectl get persistentvolumeclaims
~(keystone_admin)]$ kubectl get persistentvolumeclaims
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
test-claim1 Bound pvc-aaca.. 1Gi RWO general 2m56s
test-claim2 Bound pvc-e93f.. 1Gi RWO general 68s

2
doc/source/usertasks/kubernetes/kubernetes-user-tutorials-helm-package-manager.rst
View File

@ -27,7 +27,7 @@ Use the following command to list the helm repositories:
.. code-block:: none
~(keystone_admin)$ helm repo list
~(keystone_admin)]$ helm repo list
NAME URL
stable https://kubernetes-charts.storage.googleapis.com
local http://127.0.0.1:8879/charts

11
doc/source/usertasks/kubernetes/kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host.rst
View File

@ -108,3 +108,14 @@ You will need the following information from your |prod| administrator:
In order to use :command:`helm`, additional configuration is required.
For more information, see :ref:`Configuring Remote Helm Client
<configuring-remote-helm-client>`.
**Related information**
.. seealso::
:ref:`Configuring Container-backed Remote CLIs and Clients
<kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients>`
:ref:`Using Container-backed Remote CLIs and Clients
<using-container-based-remote-clis-and-clients>`
:ref:`Configuring Remote Helm Client <configuring-remote-helm-client>`

10
doc/source/usertasks/kubernetes/remote-cli-access.rst
View File

@ -29,3 +29,13 @@ remote workstation using one of the two methods.
:command:`helm` clients directly on the remote host. This method only
provides the kubernetes-related CLIs and requires OS-specific installation
instructions.
.. seealso::
:ref:`Configuring Container-backed Remote CLIs and Clients
<kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients>`
:ref:`Using Container-backed Remote CLIs and Clients <using-container-based-remote-clis-and-clients>`
:ref:`Installing Kubectl and Helm Clients Directly on a Host <kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host>`
:ref:`Configuring Remote Helm Client <configuring-remote-helm-client>`

7
doc/source/usertasks/kubernetes/using-an-image-from-the-local-docker-registry-in-a-container-spec.rst
View File

@ -12,6 +12,13 @@ specify an **imagePullSecret** with your keystone credentials.
.. rubric:: |context|
.. note::
If the credentials of a Keystone user is changed, you must change the
credentials stored in your **imagePullSecret** for the same user. Failure
to do so will cause docker to authenticate with Keystone using the old
credentials, and locking the Keystone user account due to too many
incorrect login attempts.
This example procedure assumes that testuser/busybox:latest container image has
been pushed to the local docker registry.

147
doc/source/usertasks/kubernetes/using-container-based-remote-clis-and-clients.rst Normal file
View File

@ -0,0 +1,147 @@
.. vja1605798752774
.. _using-container-based-remote-clis-and-clients:
==============================================
Use Container-backed Remote |CLIs| and Clients
==============================================
Remote platform |CLIs| can be used in any shell after sourcing the generated
remote CLI/client RC file. This RC file sets up the required environment
variables and aliases for the remote |CLI| commands.
.. rubric:: |prereq|
.. note::
Consider adding this command to your .login or shell rc file, such that
your shells will automatically be initialized with the environment
variables and aliases for the remote CLI commands.
Otherwise, execute the following before proceeding:
.. code-block:: none
root@myclient:/home/user/remote_cli_wd# source remote_client_platform.sh
If you specified repositories that require authentication when configuring
the container-backed remote |CLIs|, you must perform a :command:`docker
login` to that repository before using remote |CLIs| for the first time
You must have completed the configuration steps described in :ref:`Configuring
Container-backed Remote CLIs and Clients
<kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients>`
before proceeding.
.. rubric:: |proc|
- For Kubernetes :command:`kubectl` |CLI| commands:
.. note::
The first usage of a remote |CLI| command will be slow as it requires
that the docker image supporting the remote CLIs/clients be pulled from
the remote registry.
.. code-block:: none
Please enter your OpenStack Password for project tenant1 as user user1:
root@myclient:/home/user/remote_cli_wd# kubectl -n kube-system get pods
NAME READY STATUS RESTARTS AGE
calico-kube-controllers-767467f9cf-wtvmr 1/1 Running 1 3d2h
calico-node-j544l 1/1 Running 1 3d
calico-node-ngmxt 1/1 Running 1 3d1h
calico-node-qtc99 1/1 Running 1 3d
calico-node-x7btl 1/1 Running 4 3d2h
ceph-pools-audit-1569848400-rrpjq 0/1 Completed 0 12m
ceph-pools-audit-1569848700-jhv5n 0/1 Completed 0 7m26s
ceph-pools-audit-1569849000-cb988 0/1 Completed 0 2m25s
coredns-7cf476b5c8-5x724 1/1 Running 1 3d2h
...
root@myclient:/home/user/remote_cli_wd#
.. note::
Some |CLI| commands are designed to leave you in a shell prompt, for
example:
.. code-block:: none
root@myclient:/home/user/remote_cli_wd# openstack
or
.. code-block:: none
root@myclient:/home/user/remote_cli_wd# kubectl exec -ti <pod_name> -- /bin/bash
In most cases, the remote CLI will detect and handle these commands
correctly. If you encounter cases that are not handled correctly, you
can force-enable or disable the shell options using the <FORCE\_SHELL>
or <FORCE\_NO\_SHELL> variables before the command.
For example:
.. code-block:: none
root@myclient:/home/user/remote_cli_wd# FORCE_SHELL=true kubectl exec -ti <pod_name> -- /bin/bash
root@myclient:/home/user/remote_cli_wd# FORCE_NO_SHELL=true kubectl exec <pod_name> -- ls
You cannot use both variables at the same time.
- If you need to run a remote |CLI| command that references a local file,
then that file must be copied to or created in the working directory specified
in the -w option on the ./config\_client.sh command.
For example:
.. code-block:: none
root@myclient:/home/user# cp /<someDir>/test.yml $HOME/remote_cli_wd/test.yml
root@myclient:/home/user# cd $HOME/remote_cli_wd
root@myclient:/home/user/remote_cli_wd# kubectl -n kube-system create -f test.yml
pod/test-pod created
root@myclient:/home/user/remote_cli_wd# kubectl -n kube-system delete -f test.yml
pod/test-pod deleted
- Do the following to use helm.
.. xreflink
.. note::
For non-admin users, additional configuration is required first as
discussed in |sec-doc|: :ref:`Configuring Remote Helm Client for
Non-Admin Users <configuring-remote-helm-client-for-non-admin-users>`.
.. note::
When using helm, any command that requires access to a helm repository
\(managed locally\) will require that you be in the
$HOME/remote\_cli\_wd directory and use the --home ./.helm option.
#. Do the initial setup of the helm client.
.. note::
This command assumes you are using Helm v2.
.. code-block:: none
% cd $HOME/remote_cli_wd
% helm init --client-only --home "./.helm"
#. Run a helm command.
.. code-block:: none
% cd $HOME/remote_cli_wd
% helm list
% helm install --name wordpress stable/wordpress --home "./.helm"
**Related information**
.. seealso::
:ref:`Configuring Container-backed Remote CLIs and Clients <kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients>`
:ref:`Installing Kubectl and Helm Clients Directly on a Host <kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host>`
:ref:`Configuring Remote Helm Client <configuring-remote-helm-client>`

3
doc/source/usertasks/kubernetes/using-kubernetes-cpu-manager-static-policy.rst
View File

@ -14,8 +14,7 @@ Kubernetes CPU manager static policy.
You will need to enable this CPU management mechanism before applying a
policy.
.. See |admintasks-doc|: :ref:`Optimizing Application Performance
<kubernetes-cpu-manager-policies>` for details.
See |admintasks-doc|: :ref:`Optimizing Application Performance <kubernetes-cpu-manager-policies>` for details on how to enable this CPU management mechanism.
.. rubric:: |proc|

3
doc/source/usertasks/kubernetes/using-network-attachment-definitions-in-a-container.rst
View File

@ -39,6 +39,7 @@ devices as you have network annotations.
name: pod1
annotations:
k8s.v1.cni.cncf.io/networks: '[
{ "name": "net2" },
{ "name": "net2" }
]'
spec:
@ -58,7 +59,7 @@ devices as you have network annotations.
.. code-block:: none
~(keystone_admin)$ kubectl create -f pod1.yaml
~(keystone_admin)]$ kubectl create -f pod1.yaml
pod/pod1 created
After creating the container, an extra network device interface, **net2**,