content: port onboarding doc from google docs #25
Conversation
squat
force-pushed
the
add_onboarding_doc
branch
2 times, most recently
from
137c6b9 to
b3e8f32
Compare
Signed-off-by: Lucas Servén Marín <[email protected]>
squat
force-pushed
the
add_onboarding_doc
branch
from
b3e8f32 to
33adda3
Compare
There was a problem hiding this comment.
This works as a port of an internal document 👍
I think there are bits of this process we can improve - namely that a user should have received our ok to join before creating all of the relevant secrets.
Also - I think we should replace all references to Observatorium with RHOBS.
|
|
||
| ## 1. Collect Requirements | ||
|
|
||
| The first step is to collect information about the team’s requirements. The following questions should be answered: |
There was a problem hiding this comment.
Where is this information generally stored? Do we have any previous examples of this?
There was a problem hiding this comment.
Perhaps the person who wants to onboard should include this in a private Jira ticket.
There was a problem hiding this comment.
Ah ok this information is supplied in a Jira ticket in the last step.
| 3. What is the expected or forecasted growth in collected data? X% growth in data per month? | ||
| 4. How many users will require read access? X team members? The entire OpenShift org? | ||
| 5. How many clients will be emitting data? 1 Prometheus server? | ||
| 6. How long should data be retained? 2 weeks? |
There was a problem hiding this comment.
Is this something we can currently configure per-tenant? If so TIL
There was a problem hiding this comment.
Not today, but it's a valuable datapoint to know about prioritizing this feature and also knowing if we can fulfill their needs at all
There was a problem hiding this comment.
I like the 6 questions with strong suggestion of the main option we have now ;p
| - **Authors:** | ||
| - [`@squat`](https://github.com/squat) | ||
|
|
||
| ## Overview |
There was a problem hiding this comment.
Maybe worth adding that this document is for people wishing to onboard, rather than a guide for internal observatorium engineers.
There was a problem hiding this comment.
Hm, the title is not clear enough?
There was a problem hiding this comment.
'onboarding a tenant' makes me think this is a set of actions that I (rhobs engineer) need to take rather than the other way round how-to-onboard-into-rhobs would have been my choice.
There was a problem hiding this comment.
That is a good point. I think it's as easy as being exploit in first sentence below, will propose something.
| 6. How long should data be retained? 2 weeks? | ||
| 7. How many independent service accounts do you need to write data into the platform? | ||
|
|
||
| ## 2. Create a Customer Portal Account |
There was a problem hiding this comment.
This is required and gets referenced a lot of times later on. Unfortunately this is the only way that red hat currently has for providing authz, i.e. via AMS :/ we really want to change this but can't today
There was a problem hiding this comment.
Makes sense - worth adding that to the text then too.
There was a problem hiding this comment.
hmm I don't think that the new tenant needs to know the politics about why we have to use AMS but I agree they could benefit from more context about the need for this step
There was a problem hiding this comment.
I would focus rather on creating Epic/Ticket which outlines today's pain points so we can figure out in the future.
|
|
||
| ## 1. Collect Requirements | ||
|
|
||
| The first step is to collect information about the team’s requirements. The following questions should be answered: |
There was a problem hiding this comment.
| The first step is to collect information about the team’s requirements. The following questions should be answered: | |
| The first step is to collect information about the team’s requirements, this information will be required when the request to onboard into RHOBS is raised in section 5 below. The following questions should be answered: |
|
|
||
| ## 0. Register Service Accounts and Configure RBAC | ||
|
|
||
| Before configuring any clients, follow the steps in the [Observatorium Tenant Onboarding doc (internal)](https://docs.google.com/document/d/1pjM9RRvij-IgwqQMt5q798B_4k4A9Y16uT2oV9sxN3g/edit) to register the necessary service accounts and give them the required permissions on the Observatorium platform. The result of this process should be an OAuth client ID and client secret pair for each new service account. Save these credentials somewhere secure. | ||
| Before configuring any clients, follow the steps in the [RHOBS Tenant Onboarding doc](onboarding-a-tenant-into-rhobs.md) to register the necessary service accounts and give them the required permissions on the Observatorium platform. The result of this process should be an OAuth client ID and client secret pair for each new service account. Save these credentials somewhere secure. |
There was a problem hiding this comment.
| Before configuring any clients, follow the steps in the [RHOBS Tenant Onboarding doc](onboarding-a-tenant-into-rhobs.md) to register the necessary service accounts and give them the required permissions on the Observatorium platform. The result of this process should be an OAuth client ID and client secret pair for each new service account. Save these credentials somewhere secure. | |
| Before configuring any clients, follow the steps in the [RHOBS Tenant Onboarding doc](onboarding-a-tenant-into-rhobs.md) to register the necessary service accounts and give them the required permissions on the RHOBS platform. The result of this process should be an OAuth client ID and client secret pair for each new service account. Save these credentials somewhere secure. |
| @@ -7,11 +7,11 @@ | |||
|
|
|||
| ## Overview | |||
|
|
|||
| Teams that have identified a need for collecting their logs and/or metrics into a centralized service that offers querying and dashboarding may choose to send their data to Red Hat’s hosted Observatorium instance. This document details how to configure clients, such as Prometheus, to remote write data for tenants who have been onboarded to Observatorium following the team’s onboarding doc: [Onboarding a Tenant into Observatorium (internal)](https://docs.google.com/document/d/1pjM9RRvij-IgwqQMt5q798B_4k4A9Y16uT2oV9sxN3g/edit). | |||
| Teams that have identified a need for collecting their logs and/or metrics into a centralized service that offers querying and dashboarding may choose to send their data to Red Hat’s hosted Observatorium instance. This document details how to configure clients, such as Prometheus, to remote write data for tenants who have been onboarded to Observatorium following the team’s onboarding doc: [Onboarding a Tenant into RHOBS](onboarding-a-tenant-into-rhobs.md). | |||
There was a problem hiding this comment.
| Teams that have identified a need for collecting their logs and/or metrics into a centralized service that offers querying and dashboarding may choose to send their data to Red Hat’s hosted Observatorium instance. This document details how to configure clients, such as Prometheus, to remote write data for tenants who have been onboarded to Observatorium following the team’s onboarding doc: [Onboarding a Tenant into RHOBS](onboarding-a-tenant-into-rhobs.md). | |
| Teams that have identified a need for collecting their logs and/or metrics into a centralized service that offers querying and dashboarding may choose to send their data to RHOBS. This document details how to configure clients, such as Prometheus, to remote write data for tenants who have been onboarded to Observatorium following the team’s onboarding doc: [Onboarding a Tenant into RHOBS](onboarding-a-tenant-into-rhobs.md). |
| - **Authors:** | ||
| - [`@squat`](https://github.com/squat) | ||
|
|
||
| ## Overview |
There was a problem hiding this comment.
That is a good point. I think it's as easy as being exploit in first sentence below, will propose something.
|
|
||
| ## Overview | ||
|
|
||
| Teams that have identified a need for collecting their logs and/or metrics into a centralized service that offers querying and dashboarding may choose to send their data to Red Hat’s hosted Observatorium instance. This document details the steps required to become a new tenant. |
There was a problem hiding this comment.
| Teams that have identified a need for collecting their logs and/or metrics into a centralized service that offers querying and dashboarding may choose to send their data to Red Hat’s hosted Observatorium instance. This document details the steps required to become a new tenant. | |
| Teams that have identified a need for collecting their logs and/or metrics into a centralized service that offers querying and dashboarding may choose to send their data to [RHOBS](README.md). This document details the required steps the interested party has to perform to become a new tenant. |
There was a problem hiding this comment.
I kind of disagree here, there's no ambiguity IMO. This document details the steps required to become a new tenant. Who else would become a new tenant? 🤔
|
|
||
| Tenants who have been onboarded to the platform should consider validating their service accounts following the instructions in the [Testing Service Accounts for New Observatorium Tenants (internal)](https://docs.google.com/document/u/1/d/1CJsdGDnduA35Me6i3atHGDJnXzMOyWVKoqaAvFkdIbU/edit) doc. | ||
|
|
||
| Once tenants have been onboarded to the platform and have validated their credentials, they can configure their clients to access Observatorium, following the instructions in the [Configuring Clients for Observatorium](configuring-clients-for-rhobs.md) doc. |
There was a problem hiding this comment.
| Once tenants have been onboarded to the platform and have validated their credentials, they can configure their clients to access Observatorium, following the instructions in the [Configuring Clients for Observatorium](configuring-clients-for-rhobs.md) doc. | |
| Once tenants have been onboarded to the platform and have validated their credentials, they can configure their clients to access RHOBS, following the instructions in the [Configuring Clients for RHOBS](configuring-clients-for-rhobs.md) doc. |
| 3. What is the expected or forecasted growth in collected data? X% growth in data per month? | ||
| 4. How many users will require read access? X team members? The entire OpenShift org? | ||
| 5. How many clients will be emitting data? 1 Prometheus server? | ||
| 6. How long should data be retained? 2 weeks? |
There was a problem hiding this comment.
I like the 6 questions with strong suggestion of the main option we have now ;p
| 6. How long should data be retained? 2 weeks? | ||
| 7. How many independent service accounts do you need to write data into the platform? | ||
|
|
||
| ## 2. Create a Customer Portal Account |
There was a problem hiding this comment.
I would focus rather on creating Epic/Ticket which outlines today's pain points so we can figure out in the future.
|
|
||
| ## 2. Create a Customer Portal Account | ||
|
|
||
| Create a Red Hat customer portal account to group all users from your team who should have access to the data. Note: any member of your account will be able to read the data collected by Observatorium for your tenant. https://sso.redhat.com |
There was a problem hiding this comment.
| Create a Red Hat customer portal account to group all users from your team who should have access to the data. Note: any member of your account will be able to read the data collected by Observatorium for your tenant. https://sso.redhat.com | |
| Create a Red Hat customer portal account to group all users from your team who should have access to the data. Note: Any member of your account will be able to read the data collected by RHOBS for your tenant. | |
| Website: https://sso.redhat.com |
|
|
||
| ## 3. Create Service Accounts for Reading/Writing Data | ||
|
|
||
| All requests reading and writing data into the Observatorium platform must be authenticated and authorized. For this reason, each tenant must provision service accounts for their data writers, e.g. Prometheus, Promtail, etc, and their data readers, e.g. Grafana to be able to make requests. Services that would also like to test their configuration in a staging environment should create additional service accounts for the staging Observatorium instance. Services must have at least one service account, which they may choose to reuse among all of their data clients. If services would like to authenticate each client independently, then an additional service account is needed for each client. These service accounts, both for production and staging, must be created in the production external SSO environment, that is, sso.redhat.com. Service accounts may be requested via a ticket for the IT User team in Service Now at the URL help.redhat.com. The service account request should specify the following requirements: |
There was a problem hiding this comment.
| All requests reading and writing data into the Observatorium platform must be authenticated and authorized. For this reason, each tenant must provision service accounts for their data writers, e.g. Prometheus, Promtail, etc, and their data readers, e.g. Grafana to be able to make requests. Services that would also like to test their configuration in a staging environment should create additional service accounts for the staging Observatorium instance. Services must have at least one service account, which they may choose to reuse among all of their data clients. If services would like to authenticate each client independently, then an additional service account is needed for each client. These service accounts, both for production and staging, must be created in the production external SSO environment, that is, sso.redhat.com. Service accounts may be requested via a ticket for the IT User team in Service Now at the URL help.redhat.com. The service account request should specify the following requirements: | |
| All requests reading and writing data into the RHOBS platform must be authenticated and authorized. For this reason, each tenant must provision service accounts for their data writers, e.g. Prometheus, Promtail, etc, and their data readers, e.g. Grafana to be able to make requests. Services that would also like to test their configuration in a staging environment should create additional service accounts for the staging Observatorium instance. Services must have at least one service account, which they may choose to reuse among all of their data clients. If services would like to authenticate each client independently, then an additional service account is needed for each client. These service accounts, both for production and staging, must be created in the production external SSO environment, that is, sso.redhat.com. Service accounts may be requested via a ticket for the IT User team in Service Now at the URL help.redhat.com. The service account request should specify the following requirements: |
There was a problem hiding this comment.
and all the mention of Observatorium really in this doc 😢
| 8. append one new allowed callback URL to the list of allowed callback URLs for the observatorium-telemeter service account: https://observatorium.api.openshift.com/oidc/<tenant>/callback | ||
| 9. append one new allowed callback URL to the list of allowed callback URLs for the observatorium-telemeter-staging service account: https://observatorium.api.stage.openshift.com/oidc/<tenant>/callback | ||
|
|
||
| ## 4. Authorize Service Accounts |
There was a problem hiding this comment.
I think what I am missing here is any mention about the infra tenant needs to send data to RHOBS, added ticket for this #26
|
Can we still have it? cc @squat (: |
|
Let's close it, since our internal docs evolved. We might want to add new onboarding doc here. |
Signed-off-by: Lucas Servén Marín [email protected]