Sepia Lab Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Tucson OpenShift Access ======

This page explains how to get access to the **Tucson OpenShift cluster (tuc-ocp)**. You do not need to know anything about OpenShift administration. You need an IBM w3id account, a Bluegroup, and one ticket.

^ Cluster console | https://console-openshift-console.apps.tuc-ocp.os.ceph.tuc.ibm.com |
^ Cluster API | https://api.tuc-ocp.os.ceph.tuc.ibm.com:6443 |
^ Login | IBM w3id (single sign-on) |
^ Access requests | [[https://tracker.ceph.com/projects/internal_lab/issues/new|Create a ticket in the Internal Lab tracker]] |

===== How access works (in short) =====

  * You log in with your **w3id**. There are no separate passwords.
  * What you can do is decided by **Bluegroup membership**. If you are in the right Bluegroup, you get the right access to your project. If you leave the Bluegroup, you lose it.
  * Each project (namespace) has up to three Bluegroups: one for each access level.
  * Cluster admins do **not** add people to projects by hand. They only create your login and the project. Group membership then follows your Bluegroup automatically.

So the rule is: **Bluegroup first, ticket second.**

===== Step 1: Choose your access level =====

| **Access level** | **Bluegroup name** | **What you can do** | **Typical person** |
| Viewer | ''<project>-viewers'' | See pods, services, logs and configuration in your project. Cannot change anything. Cannot see Secrets. | Managers, auditors, new joiners |
| Developer | ''<project>-developers'' | Everything a viewer can, plus deploy and change workloads, routes, config maps and Secrets. | Engineers, CI users |
| Admin | ''<project>-admins'' | Everything a developer can, plus manage the project itself and give roles to others inside the project. | Project owners |

Choose the **lowest** level that lets you do your job. If you only deploy and debug, ask for Developer, not Admin.

Cluster-wide admin is not given per project. It is only for the platform (lab) team.

===== Step 2: Choose the project name =====

Only needed for a **new** project. For an existing project, use the name that already exists.

Rules for the project name:

  * Lowercase letters, digits and ''-'' only. No spaces, no capital letters, no underscores.
  * Up to 30 characters.
  * Must not start or end with ''-''.
  * Short and clear: the team or the purpose, for example ''ceph-test'' or ''ceph-qe-ci''.
  * Reserved, cannot be used: names starting with ''openshift'' or ''kube-'', and ''default'' and ''ldap-group-sync''.
  * The name must not already be in use. Ask in the ticket if you are not sure.

===== Step 3: Bluegroups =====

The Bluegroup names are always built from the project name. **They must match exactly**, or the ticket cannot be processed.

^ Access level ^ Bluegroup name for project ''ceph-test'' ^
| Viewer | ''ceph-test-viewers'' |
| Developer | ''ceph-test-developers'' |
| Admin | ''ceph-test-admins'' |

You only need to create the levels that you will use. Unused levels are fine.

==== If the Bluegroup does NOT exist yet (new project) ====

  - Open the Bluegroups tool: https://bluepages.ibm.com/tools/groups/protect/groupsgui.wss
  - Create the Bluegroup(s) with the exact names from the table above.
  - Add the people who need access. **A Bluegroup with no members is rejected**, so add at least one person (yourself is fine).
  - Use only these characters in the name: ''A-Z a-z 0-9 . _ -''
  - Then go to Step 4 and submit the ticket.

==== If the Bluegroup ALREADY exists (existing project) ====

  - Do **not** submit a ticket yet.
  - Ask the Bluegroup owner to **add you as a member**. Or add yourself if you are an owner.
  - Check that you are really in the group (see https://bluepages.ibm.com/tools/groups/protect/groupsgui.wss).
  - Only after you are a member, submit the ticket in Step 4.

A ticket sent before you are a member will be sent back and will only delay you.

===== Step 4: Submit the access request ticket =====

  - Open **[[https://tracker.ceph.com/projects/internal_lab/issues/new|https://tracker.ceph.com/projects/internal_lab/issues/new]]**
  - Subject: ''Tucson OpenShift access: <project name> (new / existing)'', for example ''Tucson OpenShift access: ceph-test (new)''
  - Copy the template below into the description and fill in every line.
  - Create one ticket per project. If several people from the same project need access, list all of them in **one** ticket.

<code>
Cluster:            tuc-ocp (Tucson OpenShift)
Project name:       <project, lowercase, e.g. ceph-test>
Project type:       New | Existing
Purpose:            <one line: what the project is for>

Bluegroups (must already exist, and you must be a member):
  Admins:           <project>-admins        (or "not needed")
  Developers:       <project>-developers    (or "not needed")
  Viewers:          <project>-viewers       (or "not needed")
Bluegroups created / confirmed:  Yes

Users who need to log in (IBM e-mail, as shown in w3id / Bluepages):
  1. first.last@ibm.com   - Bluegroup: <project>-developers
  2. first.last@ibm.com   - Bluegroup: <project>-viewers

Project owner / approver:  <name and IBM e-mail>
Needed until:              <date, or "permanent">
</code>

==== What each field means ====

^ Field ^ What to write ^
| Cluster | Always ''tuc-ocp''. |
| Project name | The name from Step 2. For an existing project, the exact current name. |
| Project type | **New** if the project does not exist on the cluster. **Existing** if it is already there and you only need access. |
| Purpose | One line. Helps the admins review the request. |
| Bluegroups | The Bluegroup name for each access level you want. Write "not needed" for the others. |
| Users | One line per person: IBM e-mail and the Bluegroup they belong to. Write the e-mail exactly as it appears in w3id. |
| Project owner / approver | The person who is responsible for the project and agrees to the access. |
| Needed until | A date, or "permanent". Helps with later clean-up. |

==== Good and bad examples ====

^ Good ^ Bad ^
| ''ceph-test-developers'' | ''Payments Developers'' (spaces, capitals) |
| ''jane.doe@ibm.com'' | ''Jane'' or ''jdoe'' (not an IBM e-mail) |
| "Bluegroup exists, I am a member" | "Please create the Bluegroup for me" (admins cannot create Bluegroups) |
| One ticket for the whole team | One ticket per person for the same project |

===== Step 5: What the cluster admins do =====

You do not need to do anything here. This is only so you know what is happening:

  - They check the ticket: the Bluegroups exist and the approver is correct.
  - For a new project, they create the project and its access rules on the cluster.
  - They create your login on the cluster (your w3id e-mail).
  - They load the Bluegroup members into the cluster. After this, your Bluegroup gives you your access level.
  - They update the ticket when it is done.

===== Step 6: Log in =====

After the ticket says access is ready:

**Web console**

  - Open https://console-openshift-console.apps.tuc-ocp.os.ceph.tuc.ibm.com
  - Choose **w3id** and sign in with your IBM account.
  - You will see only your own project(s).

**Command line (oc)**

<code>
oc login --web --server=https://api.tuc-ocp.os.ceph.tuc.ibm.com:6443
oc get projects
oc get pods -n <project>
</code>

===== Day-to-day changes =====

You do **not** need a ticket for these. Only change the Bluegroup:

^ I want to ... ^ What to do ^
| Add a colleague who already has a login | Add them to the right Bluegroup. Access follows automatically. |
| Change someone from Viewer to Developer | Move them to the other Bluegroup. Access changes automatically. |
| Remove someone | Remove them from the Bluegroup. Access ends automatically. |

You **do** need a ticket when:

  * Someone logs in to the cluster for the **first time** (they need a login created).
  * You want a **new project**.
  * You want a **new access level** (a new Bluegroup) for an existing project.
  * A person has left IBM or the team permanently and their login should be removed.

Group changes can take some time to appear (up to about 30 minutes, once automatic sync is active). If you still have no access after that, check the troubleshooting section below.

===== Troubleshooting =====

^ Problem ^ Likely cause ^ What to do ^
| "An authentication error occurred" at login | Your login was not created yet, or the e-mail in the ticket is different from your w3id e-mail | Check the ticket. Confirm the e-mail. Ask in the ticket. |
| I can log in, but I see no projects | You are not in the Bluegroup, or the group has not synced yet | Check your Bluegroup membership. Wait up to 30 minutes. Then update the ticket. |
| "Forbidden" when I change something | Your level is Viewer or Developer, and the action needs a higher level | Ask the project owner to move you to the right Bluegroup. |
| I cannot see Secrets | Viewer cannot read Secrets by design | Ask to be a Developer if you need it. |
| Ticket was sent back | Bluegroup missing, empty, or you were not a member | Fix the Bluegroup and reply on the ticket. |

===== Rules of use =====

  * This is a **lab** cluster. We do not keep backups unless you explicitly ask us to.
  * Do not share your login or tokens. Access is personal.
  * You can only use your own project(s). Other projects and cluster settings are not visible to you.
  * Access is reviewed. Remove people from the Bluegroup when they no longer need it.

===== Quick checklist =====

  - I know my project name (lowercase, up to 30 characters).
  - The Bluegroup(s) exist and have the exact names.
  - I am a member of the Bluegroup (for an existing project).
  - I used my IBM e-mail.
  - I submitted one ticket at https://tracker.ceph.com/projects/internal_lab/issues/new with the template filled in.