mfrancisc/ksctl

ksctl is a command-line tool to manage your installation of KubeSaw

ksctl

This repo contains kctl command-line tool that helps you to manage your instance of KubeSaw service.

ksctl binary

The prerequisite for running most of the ksctl commands is having a .ksctl.yaml config file in your home directory. If you don’t have any, please, contact one of the administrators. If you are an administrator, then read the "Admin usage" section.

Build

Requires Go version 1.20.x - download for your development environment here.

Install

To install the binary, clone the latest version of ksctl repository:

git clone https://github.com/kubesaw/ksctl.git
cd ksctl

and install the binary

make install

Cheat sheet for commands

This section covers the most useful commands. However, the ksctl binary provides other commands than those that are listed here. To see all of them, run:

ksctl --help

The ksctl --version command shows the version of the binary (based on the commit hash)

ksctl --version

Note

Prerequisite: The .ksctl.yaml config file is needed to run user-management related ksctl commands. The default location is your home directory: ~/.ksctl.yaml, but you can use the --config flag to specify a different path. It contains the configuration settings for the host and member clusters together with the granted token.

Finding UserSignup name

When users sign up, a UserSignup resource is created on their behalf on the Host cluster. For most of the user-management operations, the name of the UserSignup resource is needed.
To see all UserSignup resource names run:

$ ksctl get usersignup -t host
NAME                 USERNAME     COMPLETE   REASON            COMPLIANTUSERNAME   EMAIL
...
2237e8be-f678d76ff   dummy-name   False      PendingApproval                       [email protected]
...

The first column is the name of the UserSignup resource.

To look-up a UserSignup resource from the user’s email address, run: in Linux:

ksctl get -t host usersignups -l toolchain.dev.openshift.com/email-hash=`echo -n <email_address> | md5sum | cut -d ' ' -f 1`

in macOS:

ksctl get -t host usersignups -l toolchain.dev.openshift.com/email-hash=`echo -n <email_address> | md5`

Approving a user

To approve user, either use the user’s email:

$ ksctl approve --email <user_email>

or get the UserSignup name, and then run:

$ ksctl approve --name <usersignup_name>

Warning

By default, the approve command checks if the user already initiated the phone verification process. To skip this check for the users or environments where the a phone verification is not required, use the --skip-phone-check flag.

The command will print out additional information about the UserSignup resource to be approved and it will also ask for a confirmation.

Deactivating a user

To deprovision a user from the platform and keep his/her UserSignup resource there, use deactivate command. First get the UserSignup name, then run:

$ ksctl deactivate <usersignup_name>

The command will print out additional information about the UserSignup resource to be deactivated and it will also ask for a confirmation.

Deleting a user

To completely remove a user from the platform including his/her UserSignup resource (for example as part of a GDPR request), use the gdpr-delete command. First get the UserSignup name, then run:

$ ksctl gdpr-delete <usersignup_name>

The command will print out additional information about the UserSignup resource to be deleted and it will also ask for a confirmation.

Banning a user

To ban a user so the account is deprovisioned and the user is not able to sign up again, use the ban command. First get the UserSignup name, then run:

$ ksctl ban <usersignup_name>

The command will print out additional information about the UserSignup resource to be banned and it will also ask for a confirmation.

Creating an Event

Social Events are a feature allowing users to sign up without having to go through the phone verification process. This is useful when running labs or workshops, as it lets attendees get up and running quickly without having to fulfil all the requirements of the standard signup process.

Social Events are temporary in nature; creating an event will produce a unique activation code that may be used for a predefined period of time, after which the code will no longer work.

Use the create-event command to create a new event, specifying a description, the start-date and end-date range and max-attendees. The date range should encompass the dates of the event (it is recommended that the range actually be expanded to include the day before and after the event just to be safe), and the maximum attendees should also be slightly higher than the expected attendees in the rare case of technical difficulties or additional attendees.

Here’s an actual example:

$ ksctl create-event --description="Summit Connect Dallas / SF" --start-date=2022-09-27 --end-date=2022-09-30 --max-attendees=70

The output from this command should look something like this:

Social Event successfully created. Activation code is 'bduut'

The activation code should be kept secret, and only provided to the event organizer.

Admin usage

There is a provisioning flow for KubeSaw administrators separate from what the standard KubeSaw users use when they are signing up through the registration service. There are two ways of granting permissions to the KubeSaw administrators, either via a ServiceAccount or via an OpenShift user.

Admin manifests

The admin manifests are generated via ksctl generate admin-manifests command. The command generates manifests in a Kustomize folders, so it can be easily synced by another tool (eg. ArgoCD) to the cluster. The content of the admin manifests is defined in kubesaw-admins.yaml file, which is used also as the source for ksctl generate admin-manifests command. You can see an example of such a file in kubesaw-admins.yaml.

Clusters

The required sections of the kubesaw-admins.yaml file is a clusters section defining location and names of the clusters used in the KubeSaw instance. This is necessary for running ksctl generate cli-configs command which adds the information to all generated ksctl.yaml files.

clusters:
  host:
    api: https://api.dummy-host.openshiftapps.com:6443
  members:
  - api: https://api.dummy-m1.openshiftapps.com:6443
    name: member-1
  - api: https://api.dummy-m2.openshiftapps.com:6443
    name: member-2

Add ServiceAccount for cli usage

The serviceAccounts section contains definition of ServiceAccounts together with the granted permissions. To add a new SA that is supposed to be used in a combination with cli commands, add the following code:

serviceAccounts:
- name: <your-name>
  host:
    roleBindings:
    - namespace: toolchain-host-operator
      roles:
      - <roles-or-commands-to-be-granted>
    clusterRoleBindings:
      clusterRoles:
      - ...

  member:
    roleBindings:
    - namespace: toolchain-member-operator
      roles:
      - <roles-or-commands-to-be-granted>
    clusterRoleBindings:
      clusterRoles:
      - ...

Generate ksctl.yaml files

For each ServiceAccount defined in this section, the ksctl generate cli-configs generates a separate ksctl.yaml file with the corresponding cluster configuration and tokens. As an administrator of the clusters, run this command and distribute securely the generated ksctl.yaml files to other team members.

Users

The ksctl command can generate The users section contains definition for users, identities, and the permissions granted to them. KubeSaw uses a suffix -crtadmin for the admin usernames which are blocked from signing-up as a regular users via registration service. This ensures that provisioning admin users is fully isolated from the process of the regular ones. To add a -crtadmin user for a particular component in member cluster, update the corresponding kubesaw-admins.yaml file by adding the following code under the users section:

For an admin of the component that needs to manually approve operator updates:

users:
- name: <your-name>-crtadmin
  id:
  - <sso-identities>
  member:
    roleBindings:
    - namespace: <namespace-name>
      roles:
      - approve-operator-update
      clusterRoles:
      - admin
    clusterRoleBindings:
      clusterRoles:
      - list-operators-group

For a maintainer of the component with limited permissions:

- name: <your-name>-crtadmin
  id:
  - <sso-identities>
  member:
    roleBindings:
    - namespace: <namespace-name>
      clusterRoles:
      - <edit/view>

If you need any permissions also in a namespace in host cluster (to be used mainly by KubeSaw maintainers), then include the host section in the user’s definition as well:

- name: <your-name>-crtadmin
  id:
  - <sso-identities>
  host:
    roleBindings:
    - namespace: <namespace-name>
    ...
  member:
    roleBindings:
    - namespace: <namespace-name>
    ...