ksctl

README

= ksctl
:source-highlighter: prettify
:icons: font

image:https://github.com/kubesaw/ksctl/workflows/ci-build/badge.svg[build status]

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,"Admin usage">> section.

== Build

Requires Go version 1.20.x - download for your development environment https://golang.org/dl/[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 [[find_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                       dummy@email.com
...
```
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 a user, either use the user's email:
```
$ ksctl approve --email <user_email>
```

or <<find_usersignup_name,get the UserSignup name>>, and then run:
```
$ ksctl approve --name <usersignup_name>
```

WARNING: By default, the `approve` command checks if the user has already initiated the phone verification process. To skip this check for the users or environments where the 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 <<find_usersignup_name,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 <<find_usersignup_name,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 which in turn de-provisions the account and doesn't allow the user to sign up again, use the `ban` command. First <<find_usersignup_name,get the UserSignup name>>, second <<reason of the ban>>, then run:

```
$ ksctl ban <usersignup_name> <ban_reason>
```

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 to get up and run it quickly without having to fulfill all the requirements of the standard sign up 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 [[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 link:test-resources/dummy.openshiftapps.com/kubesaw-admins.yaml[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.

```yaml
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:

```yaml
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:
      - ...
```

===== ServiceAccount namespace location

By default, all `ServiceAccounts` are created in default namespaces:

* `kubesaw-admins-host` for the host cluster
* `kubesaw-admins-meber` for the member cluster

The default location can be changed in `kubesaw-admin.yaml` file:

```yaml
defaultServiceAccountsNamespace:
  host: your-host-namespace
  member: your-member-namespace
```

These two namespaces has to have different names.

It's also possible to override the namespace location for a given `ServiceAccount`:

```yaml
serviceAccounts:
- name: in-namespace-sa
  namespace: specific-sa-namespace
  host:
    ...
  member:
    ...
```

===== 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.

====== Testing the `ksctl generate cli-configs` command locally
1. Run `make install`
2. Create `kubesaw-admins.yaml` (as an example, check link:test-resources/dummy.openshiftapps.com/kubesaw-admins.yaml[kubesaw-admins.yaml])
3. Run `ksctl generate admin-manifests --kubesaw-admins <path>/kubesaw-admins.yaml --out-dir <admin-manifests-out-dir-path>`
4. Create resources from the `<admin-manifests-out-dir-path>` of the previous command. Please, note that you will need to create some namespaces manually (`oc create ns <namespace-name>`), such as `host-sre-namespace`, `first-component`, `second-component`, `some-component`, `member-sre-namespace`, and `crw`, for example.
- Run `oc apply -k <admin-manifests-out-dir-path>/host`
- Run `oc apply -k <admin-manifests-out-dir-path>/member`
- Run `oc apply -k <admin-manifests-out-dir-path>/member-3`
5. Run `ksctl generate cli-configs -k <kubeconfig-path> -c <path>/kubesaw-admins.yaml`


==== 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:
```yaml
users:
- name: <your-name>-maintainer
  id:
  - <sso-identities>
  member:
    roleBindings:
    - namespace: <namespace-name>
      roles:
      - view-secrets
      clusterRoles:
      - <edit/admin>
      - some-extra-permissions
    clusterRoleBindings:
      clusterRoles:
      - some-extra-cluster-scope-permissions
```
NOTE: The creation of the ClusterRoles is not managed via ksctl, you need to make sure that they are created in the cluster.

For a maintainer of the component with limited permissions:
```yaml
- name: <your-name>-maintainer
  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:
```yaml
- name: <your-name>-maintainer
  id:
  - <sso-identities>
  host:
    roleBindings:
    - namespace: <namespace-name>
    ...
  member:
    roleBindings:
    - namespace: <namespace-name>
    ...
```