343 lines
13 KiB
ReStructuredText
343 lines
13 KiB
ReStructuredText
|
|
.. fda1581955005891
|
|
.. _security-configure-container-backed-remote-clis-and-clients:
|
|
|
|
==================================================
|
|
Configure Container-backed Remote CLIs and Clients
|
|
==================================================
|
|
|
|
The |prod| command lines can be accessed from remote computers running Linux,
|
|
MacOS, and Windows.
|
|
|
|
.. rubric:: |context|
|
|
|
|
This functionality is made available using a docker container with
|
|
pre-installed CLIs and clients. The container's image is pulled as required by
|
|
the remote CLI/client configuration scripts.
|
|
|
|
.. rubric:: |prereq|
|
|
|
|
You must have a |WAD| or Local |LDAP| username and password to get the
|
|
Kubernetes authentication token, a Keystone username and password to log
|
|
into Horizon, the |OAM| IP and, optionally, the Kubernetes |CA| certificate of
|
|
the target |prod| environment.
|
|
|
|
You must have Docker installed on the remote systems you connect from. For
|
|
more information on installing Docker, see
|
|
`https://docs.docker.com/install/ <https://docs.docker.com/install/>`__.
|
|
For Windows remote clients, Docker is only supported on Windows 10.
|
|
|
|
.. note::
|
|
You must be able to run docker commands using one of the following options:
|
|
|
|
.. _security-configure-container-backed-remote-clis-and-clients-d70e42:
|
|
|
|
- Running the scripts using sudo
|
|
|
|
- Adding the Linux user to the docker group
|
|
|
|
For more information, see,
|
|
`https://docs.docker.com/engine/install/linux-postinstall/
|
|
<https://docs.docker.com/engine/install/linux-postinstall/>`__
|
|
|
|
For Windows remote clients, you must run the following commands from a
|
|
Cygwin terminal. See `https://www.cygwin.com/ <https://www.cygwin.com/>`__
|
|
for more information about the Cygwin project.
|
|
|
|
For Windows remote clients, you must also have :command:`winpty` installed.
|
|
Download the latest release tarball for Cygwin from
|
|
`https://github.com/rprichard/winpty/releases
|
|
<https://github.com/rprichard/winpty/releases>`__. After downloading the
|
|
tarball, extract it to any location and change the Windows <PATH> variable
|
|
to include its bin folder from the extracted winpty folder.
|
|
|
|
The following procedure shows how to configure the Container-backed Remote CLIs
|
|
and Clients for an admin user with cluster-admin clusterrole. If using a
|
|
non-admin user such as one with privileges only within a private namespace,
|
|
additional configuration is required in order to use :command:`helm`.
|
|
The following procedure shows how to configure the Container-backed Remote
|
|
CLIs and Clients for an admin user with cluster-admin clusterrole.
|
|
|
|
.. rubric:: |proc|
|
|
|
|
|
|
.. _security-configure-container-backed-remote-clis-and-clients-d70e93:
|
|
|
|
#. In the active controller, log in through SSH or local console using
|
|
**sysadmin** user and do the actions listed below.
|
|
|
|
#. Configure Kubernetes permissions for users.
|
|
|
|
#. Source the platform environment
|
|
|
|
.. code-block:: none
|
|
|
|
$ source /etc/platform/openrc
|
|
~(keystone_admin)]$
|
|
|
|
#. Create a user rolebinding file. You can customize the name of the
|
|
user. Alternatively, to use group rolebinding and user group
|
|
membership for authorization, see :ref:`Configure Users, Groups, and
|
|
Authorization <configure-users-groups-and-authorization>`
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ MYUSER="admin-user"
|
|
~(keystone_admin)]$ cat <<EOF > admin-user-rolebinding.yaml
|
|
kind: ClusterRoleBinding
|
|
apiVersion: rbac.authorization.k8s.io/v1
|
|
metadata:
|
|
name: ${MYUSER}-rolebinding
|
|
roleRef:
|
|
apiGroup: rbac.authorization.k8s.io
|
|
kind: ClusterRole
|
|
name: cluster-admin
|
|
subjects:
|
|
- apiGroup: rbac.authorization.k8s.io
|
|
kind: User
|
|
name: ${MYUSER}
|
|
EOF
|
|
|
|
#. Apply the rolebinding.
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ kubectl apply -f admin-user-rolebinding.yaml
|
|
|
|
#. Note the |OAM| IP address to be used later in the creation of the
|
|
kubeconfig file.
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ system oam-show | grep oam_floating_ip | awk '{print $4}'
|
|
|
|
Use the command below in |AIO-SX| environments. |AIO-SX| uses <oam_ip>
|
|
instead of <oam_floating_ip>.
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ system oam-show | grep oam_ip | awk '{print $4}'
|
|
|
|
#. If HTTPS has been enabled for the |prod| RESTAPI Endpoints on your
|
|
|prod| system, execute the following commands to create the |CA|
|
|
certificate and copy it to the remote workstation.
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ kubectl get secret system-local-ca -n cert-manager -o=jsonpath='{.data.ca\.crt}' | base64 --decode > /home/sysadmin/stx.ca.crt
|
|
~(keystone_admin)]$ scp /home/sysadmin/stx.ca.crt <remote_workstation_user>@<remote_workstation_IP>:~/stx.ca.crt
|
|
|
|
#. Optional: copy the Kubernetes |CA| certificate
|
|
``/etc/kubernetes/pki/ca.crt`` from the active controller to the remote
|
|
workstation. This step is strongly recommended, but it still possible
|
|
to connect to the Kubernetes cluster without this certificate.
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ scp /etc/kubernetes/pki/ca.crt <remote_workstation_user>@<remote_workstation_IP>:~/k8s-ca.crt
|
|
|
|
#. In the remote workstation, do the actions listed below.
|
|
|
|
#. Copy the remote client tarball file from the |prod| build servers
|
|
to the remote workstation, and extract its content.
|
|
|
|
- The tarball is available from the StarlingX Public build servers.
|
|
|
|
- You can extract the tarball's contents anywhere on your client system.
|
|
|
|
.. parsed-literal::
|
|
|
|
$ cd $HOME
|
|
$ tar xvf |prefix|-remote-clients-<version>.tgz
|
|
|
|
#. Download the user/tenant openrc file from the Horizon Web interface to
|
|
the remote workstation.
|
|
|
|
#. Log in to Horizon as the user and tenant that you want to configure
|
|
remote access for.
|
|
|
|
In this example, the 'admin' user in the 'admin' tenant.
|
|
|
|
#. Navigate to **Project** \> **API Access** \> **Download Openstack RC
|
|
file**.
|
|
|
|
#. Select **Openstack RC file**.
|
|
|
|
The file ``admin-openrc.sh`` downloads. Copy this file to the
|
|
location of the extracted tarball.
|
|
|
|
.. note::
|
|
|
|
For a Distributed Cloud system, navigate to **Project** \> **Central
|
|
Cloud Regions** \> **RegionOne** \> and download the **Openstack RC
|
|
file**.
|
|
|
|
#. If HTTPS has been enabled for the |prod| RESTAPI Endpoints on your
|
|
|prod| system, add the following line to the bottom of
|
|
``admin-openrc.sh``:
|
|
|
|
.. code-block:: none
|
|
|
|
export OS_CACERT=<path_to_ca>
|
|
|
|
where ``<path_to_ca>`` is the absolute path of the file ``stx.ca.crt``
|
|
acquired in the steps above.
|
|
|
|
#. Create an empty admin-kubeconfig file on the remote workstation using
|
|
the following command.
|
|
|
|
.. code-block:: none
|
|
|
|
$ touch admin-kubeconfig
|
|
|
|
#. Configure remote CLI/client access.
|
|
|
|
This step will also generate a remote CLI/client RC file.
|
|
|
|
#. Change to the location of the extracted tarball.
|
|
|
|
.. parsed-literal::
|
|
|
|
$ cd $HOME/|prefix|-remote-clients-<version>/
|
|
|
|
#. Create a working directory that will be mounted by the container
|
|
implementing the remote |CLIs|.
|
|
|
|
See the description of the :command:`configure_client.sh` -w option
|
|
below for more details.
|
|
|
|
.. code-block:: none
|
|
|
|
$ mkdir -p $HOME/remote_cli_wd
|
|
|
|
#. Run the :command:`configure_client.sh` script.
|
|
|
|
.. parsed-literal::
|
|
|
|
$ ./configure_client.sh -t platform -r admin-openrc.sh -k admin-kubeconfig -w HOME/remote_cli_wd -p docker.io/starlingx/stx-platformclients:|v_starlingx-stx-platformclients|
|
|
|
|
If you specify repositories that require authentication, as shown
|
|
above, you must first perform a :command:`docker login` to that
|
|
repository before using remote |CLIs|. WRS |AWS| ECR credentials or
|
|
a |CA| certificate is required.
|
|
|
|
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).
|
|
|
|
The default value is platform.
|
|
|
|
``-r``
|
|
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.
|
|
|
|
The default value is temp-kubeconfig.
|
|
|
|
``-o``
|
|
The remote CLI/client RC file generated by this script.
|
|
|
|
This RC file needs to be sourced in the shell, to setup required
|
|
environment variables and aliases, before running any remote
|
|
|CLI| commands.
|
|
|
|
For the platform client setup, the default is
|
|
remote_client_platform.sh. For the openstack application client
|
|
setup, the default is remote_client_app.sh.
|
|
|
|
``-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 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.
|
|
|
|
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:
|
|
|
|
.. parsed-literal::
|
|
|
|
$ ./configure_client.sh -t platform -r admin-openrc.sh -k admin-kubeconfig -w $HOME/remote_cli_wd -p docker.io/starlingx/stx-platformclients:|v_starlingx-stx-platformclients|
|
|
|
|
If you specify repositories that require authentication, you
|
|
must first perform a :command:`docker login` to that repository
|
|
before using remote |CLIs|.
|
|
|
|
``-a``
|
|
Override the OpenStack application image.
|
|
|
|
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.
|
|
|
|
#. Copy the file ``remote_client_platform.sh`` to ``$HOME/remote_cli_wd``
|
|
|
|
#. Update the contents in the admin-kubeconfig file using the
|
|
:command:`kubectl` command from the container. Use the |OAM| IP address
|
|
and the Kubernetes |CA| certificate acquired in the steps above. If the
|
|
|OAM| IP is IPv6, use the IP enclosed in brackets (example:
|
|
"[fd00::a14:803]").
|
|
|
|
.. code-block:: none
|
|
|
|
$ cd $HOME/remote_cli_wd
|
|
$ source remote_client_platform.sh
|
|
$ kubectl config set-cluster wrcpcluster --server=https://<OAM_IP>:6443
|
|
$ kubectl config set clusters.wrcpcluster.certificate-authority-data $(base64 -w0 k8s-ca.crt)
|
|
$ kubectl config set-context ${MYUSER}@wrcpcluster --cluster=wrcpcluster --user ${MYUSER}
|
|
$ kubectl config use-context ${MYUSER}@wrcpcluster
|
|
|
|
If you don't have the Kubernetes |CA| certificate, execute the following
|
|
commands instead.
|
|
|
|
.. code-block:: none
|
|
|
|
$ cd $HOME/remote_cli_wd
|
|
$ source remote_client_platform.sh
|
|
$ kubectl config set-cluster wrcpcluster --server=https://<OAM_IP>:6443 --insecure-skip-tls-verify
|
|
$ kubectl config set-context ${MYUSER}@wrcpcluster --cluster=wrcpcluster --user ${MYUSER}
|
|
$ kubectl config use-context ${MYUSER}@wrcpcluster
|
|
|
|
.. 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 CLI/client RC file. This RC file sets up the required environment
|
|
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.
|
|
|
|
See :ref:`Using Container-backed Remote CLIs and Clients
|
|
<using-container-backed-remote-clis-and-clients>` for details.
|
|
|
|
**Related information**
|
|
|
|
.. seealso::
|
|
|
|
:ref:`Using Container-backed Remote CLIs and Clients
|
|
<using-container-backed-remote-clis-and-clients>`
|
|
|
|
:ref:`Install Kubectl and Helm Clients Directly on a Host
|
|
<security-install-kubectl-and-helm-clients-directly-on-a-host>`
|