clients/remote_cli/README

Copyright (c) 2019 Wind River Systems, Inc.
SPDX-License-Identifier: Apache-2.0
--------------------------------------------------


StarlingX Remote CLI Clients
--------------------------------------------------

To enable access to StarlingX CLI remotely, docker images
containing the CLI and Client packages have been created,
for installation on a remote workstation.  Two CLI/Client
docker images are used; one for the Kubernetes platform
CLIs/Clients and one for the OpenStack application CLIs/Clients.

This SDK Module includes scripts to configure and provide aliases
for Kubernetes platform and OpenStack application CLI.


Dependencies
-------------------------------------------------
Please make sure Docker is installed on the remote workstation
before using the remote CLI clients. The proper docker images
are pulled automatically by the client scripts.

For instructions on how to install Docker for your system please
follow instructions at the following link: https://docs.docker.com/install/

On Windows, cygwin and winpty need to be installed as well.
Follow instruction on how to install cygwin at: https://www.cygwin.com/

For winpty, download the latest release tarball for cygwin
at https://github.com/rprichard/winpty/releases
After downloading the tarball, extract it to any location and change the
Windows PATH variable to include "bin" folder from the extracted
winpty folder


Using the Remote CLI Clients on a Linux machine:
------------------------------------------------
To install the clients on a Linux machine follow these steps:

1.   Untar the provided SDK module tarball

     If you want to use your own docker images for remote-clients or
     pushed the default images to your own private docker registry,
     you can edit the PLATFORM_DOCKER_IMAGE and APPLICATION_DOCKER_IMAGE
     variables in the docker_image_versions.sh file.

     NOTE: If you are pulling images from custom docker registries that require
           authentication, use the "docker login" command to login to that custom
           registry, before attempting to run commands for the first time.

2.   Download the openrc file from Horizon.
     Log in to Horizon as the user and tenant that you want to use the
     remote CLIs as, go to:
     Project -> API Access -> Download Openstack RC file -> Openstack RC file
     NOTE: You can do this for either the Kubernetes platform Horizon or
           OpenStack application Horizon side, or both

3.   For kubectl and helm commands to work remotely, you must configure a kubernetes
     service account on the target system and generate a configuration file based
     on that service account. The following script is provided to automate the
     creation of the service account and generation of the configuration file.
     Run the following commands logged in as root.

USER="adminuser"
OUTPUT_FILE="temp-kubeconfig"

cat <<EOF > admin-login.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: ${USER}
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-user
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: ${USER}
  namespace: kube-system
EOF

kubectl apply -f admin-login.yaml
TOKEN_DATA=$(kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep ${USER} | awk '{print $1}') | grep "token:" | awk '{print $2}')
source /etc/platform/openrc
OAM_IP=$(system oam-show |grep oam_floating_ip| awk '{print $4}')
if [ -z "$OAM_IP" ]; then
    # AIO-SX doesn't use oam_floating_ip, but instead uses just oam_ip
    OAM_IP=$(system oam-show |grep oam_ip| awk '{print $4}')
fi
# If it's an IPv6 address we must enclose it in brackets
if [[ $OAM_IP =~ .*:.* ]]; then
    OAM_IP="[${OAM_IP}]"
fi



kubectl config --kubeconfig ${OUTPUT_FILE} set-cluster stxcluster --server=https://${OAM_IP}:6443 --insecure-skip-tls-verify
kubectl config --kubeconfig ${OUTPUT_FILE} set-credentials ${USER} --token=$TOKEN_DATA
kubectl config --kubeconfig ${OUTPUT_FILE} set-context stxcluster-default --cluster=stxcluster --user ${USER} --namespace=default
kubectl config --kubeconfig ${OUTPUT_FILE} use-context stxcluster-default


     You can customize the service account name and the output configuration file
     by changing the USER and OUTPUT_FILE variables.

     Copy the generated file on the machine where the remote clients are deployed.
     The file should be given as a parameter to the "configure_client" script.

4.   Configure the clients for Kubernetes platform / OpenStack application side
     Kubernetes platform side:
         ./configure_client.sh -t platform -r admin_openrc.sh -k temp-kubeconfig
         By default this will generate a remote_client_platform.sh file
     Openstack application side:
         ./configure_client.sh -t openstack -r admin_openrc.sh
         By default this will generate a remote_client_openstack.sh file

5.   When access to the Kubernetes platform side is required, on your console,
     source the platform side generated at step 4.
     Example: source remote_client_platform.sh

     When access to the Openstack application side is required, on your console,
     source the platform side generated at step 4.
     Example: source remote_client_openstack.sh

     When prompted, enter your openstack password.

     And then execute either platform or openstack application CLI commands

     The sourcing of the config files will also populate aliases for
     platform/application clients.

     NOTE: do not source both the platform and application config
           files from the same console. To use both the kubernetes
           platform and openstack application remote clients, source
           each config file from separate consoles.

6.   For commands that require local filesystem access, you can configure a work
     directory as part of the configure_client.sh script.

     The configuration parameter is "-w" and by default it uses the local folder
     from where the configuration script was called.

     This working directory is mounted at "/wd" in the docker container.

     If commands need access to local files, copy the files in your configured
     work directory and then provide the command with the path to the mounted
     folder inside the container.

     Example (uploading an image to glance for the openstack application):
     1. cp centos63.qcow2 <configured_work_dir>/

     2. openstack image create --disk-format qcow2 --container-format bare \
       --public --file /wd/centos63.qcow2 centos63-image

7.   Some commands used by remote CLI are designed to leave you in a shell prompt.
     Examples of such commands are "openstack" or "kubectl exec -ti <pod_name>
     -- /bin/bash". There are cases where the mechanism for identifying commands
     that should leave you in a shell prompt is not identifying them correctly.
     If users encounter such scenarios, they can force the shell or force disable
     the shell options using the FORCE_SHELL or FORCE_NO_SHELL variables before
     the command. You cannot use both variables at the same time.

     Examples:
     - force shell: FORCE_SHELL=true kubectl exec -ti <pod_name> -- /bin/bash
     - disable shell: FORCE_NO_SHELL=true kubectl exec <pod_name> -- ls