-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into remove-satori
- Loading branch information
Showing
36 changed files
with
2,372 additions
and
151 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,249 @@ | ||
| = 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 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 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 <<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 so the account is deprovisioned and the user is not able to sign up again, use the `ban` command. First <<find_usersignup_name,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 [[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: | ||
| - ... | ||
| ``` | ||
|
|
||
| ===== 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: | ||
| ```yaml | ||
| 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: | ||
| ```yaml | ||
| - 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: | ||
| ```yaml | ||
| - name: <your-name>-crtadmin | ||
| id: | ||
| - <sso-identities> | ||
| host: | ||
| roleBindings: | ||
| - namespace: <namespace-name> | ||
| ... | ||
| member: | ||
| roleBindings: | ||
| - namespace: <namespace-name> | ||
| ... | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.