Skip to content

docs: add organizations, provisioners, and premium license docs #14778

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 33 commits into from
Oct 1, 2024

Conversation

bpmct
Copy link
Member

@bpmct bpmct commented Sep 24, 2024

Anything I am missing?


Preview this

Introduce a new guide for managing organizations under a Coder
deployment. This document provides step-by-step instructions for
setting up and utilizing organizations to segment and isolate
resources for different user groups or projects.

Changes:
- Added `organizations.md` guide in `docs/admin`
- Renamed and relocated relevant images to `docs/images/admin/organizations`
- Updated `manifest.json` to include the new organizations guide
- Removed the obsolete "Using Organizations" guide

This change facilitates better organization of the admin
documentation and aligns with the introduction of enterprise
features requiring a premium license.
Switch the icon for the organizations guide to provide better
visual representation and consistency with other documentation.

- Use "orgs.svg" instead of "group.svg" for the organizations guide.
@bpmct bpmct changed the title docs: add docs for organizations & Premium license docs: add organizations, provisioners, and premium license docs Sep 24, 2024
- Changed the `state` of the RBAC documentation entry in `manifest.json`
  to an array allowing for multiple states.
- Added "beta" as an additional state alongside "enterprise" to
  highlight that this feature is also in beta testing.
Organizations is in beta. If you encounter any issues, please
- [file an issue](https://github.com/coder/coder/issues/new)
- Contact your account team

Remove outdated using-organizations guide

This guide was outdated and redundant with the more comprehensive
documentation found in the admin section.
@mattvollmer
Copy link
Contributor

mattvollmer commented Sep 24, 2024

I think on pages like this we decided to keep the enterprise pill and add the premium pill next to it, right @stirby? The goal is to avoid alienating or confusing existing enterprise customers.

image

@bpmct
Copy link
Member Author

bpmct commented Sep 24, 2024 via email

@stirby
Copy link
Collaborator

stirby commented Sep 24, 2024

Thank you for picking this up @bpmct. Also see coder.com/docs/enterprise.

Need to

  • Rename to Premium

Like to

  • add OSS features so the "Community Edition" is not all X's (see coder.com/pricing)
  • Explain the difference between premium and enterprise (deprecated) licenses for existing customers

Later, I'd like to move this page into a new licensing/ section of the docs, briefly explaining how to manage license keys.

For now, I think temporary removal would be sufficient.

@bpmct
Copy link
Member Author

bpmct commented Sep 24, 2024

Sound good, I'll get to that a bit later in the week.

@mattvollmer
Copy link
Contributor

Here is a preview of the updated coder.com/pricing page:
https://codercom-7dmjk1fjn-codercom.vercel.app/pricing#compare-plans

So that we don't have to manage the same features in two different places, should we:

  1. Direct people to coder.com/pricing from Docs, or...
  2. Pull in this component to Docs: coder.com/src/components/Pricing/comparison.tsx, or...
  3. ...

@Kira-Pilot Kira-Pilot added the multi-org temporary label for multiple organizations related work label Sep 24, 2024
@bpmct
Copy link
Member Author

bpmct commented Sep 25, 2024

Here is a preview of the updated coder.com/pricing page: https://codercom-7dmjk1fjn-codercom.vercel.app/pricing#compare-plans

So that we don't have to manage the same features in two different places, should we:

  1. Direct people to coder.com/pricing from Docs, or...
  2. Pull in this component to Docs: coder.com/src/components/Pricing/comparison.tsx, or...
  3. ...

I'm leaning towards #1 for simplicity sake. I'll link all of the pills to coder.com/pricing and make it open in a new tab

@bpmct
Copy link
Member Author

bpmct commented Sep 25, 2024

I couldn't access my dogfood workspace tonight so no progress. Will finish remaining items tomorrow for sure 👍🏼

Remove references to the now-deleted enterprise page across various
docs. New URL points directly to the pricing page.

- Removed enterprise links from docs
- Updated enterprise links to point directly to pricing page
- Emphasize benefits of running external provisioners.
- Update authentication information with detailed steps and examples.
- Reorganize and clarify the types and scopes of provisioners.
- Provide detailed example commands and common use cases for each type.
- Enhance security guidance and best practices.

```sh
- Improved explanations of the types and scopes of provisioners
- Added commands for creating and authenticating provisioners
- Provided step-by-step instructions for running provisioners
- Updated examples for Kubernetes, Docker, and VM setups

Provisioners are now easier to understand and configure, especially with new scoped key options and user token examples. This ensures better security and operational efficiency.
@bpmct
Copy link
Member Author

bpmct commented Sep 25, 2024

@Kira-Pilot thanks for adding "Migration guide for moving group in a deployment over to orgs." Is it cool if I extract that to an issue that we do after the October release?

@bpmct bpmct requested a review from Emyrk September 25, 2024 12:29
bpmct and others added 6 commits September 25, 2024 16:28
- Change "enterprise" references to "premium" to reflect the new branding.
- Ensure consistency across various documentation sections.
- Update relevant links and terms for clarity.

### Changes:

- Appearance section title updated to include premium.
- SCIM, Group Sync, Role Sync, and multiple other sections retitled for premium.
- FAQs and guides updated to reflect new premium terminology.
- Manifest JSON entries updated to list "premium" alongside "enterprise".
- Networking and port forwarding documentation updated to include premium.
- Added user quiet hours and autostop requirement sections updated to indicate premium.
- Ensure all references in various docs are consistent with the new premium branding.
- Improve directions and clarity for enabling group sync
- Introduce new licensing guide for setting up premium features

Changes:
- Detailed steps and examples added for configuring OIDC claims
- New `licensing.md` guide presents ways to add a license via UI and CLI
- Introduced new enterprise SVG icon for better visual representation

These updates aim to enhance the user experience and provide clear, actionable instructions.
adds new feature sections

### To do

- [x] populate or delete scope of support sections
   - [ ] if populate, then:
      - what should people expect
      - how/where do they get it
- [x] rm Alpha?
- [ ] ~link to wikipedia?~
- ~EA:
<https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha>~
- ~Experimental:
<https://en.wikipedia.org/wiki/Software_release_life_cycle#Feature-complete>~
- ~Beta:
<https://en.wikipedia.org/wiki/Software_release_life_cycle#Open_and_closed_beta>~

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
To provide clarity on where to find the user's OIDC groups and roles,
instructions were added to check both `id_token_claims` and
`user_info_claims`.

Enhanced examples include exact steps:
- How to use group IDs for configuring synchronization.
- Mapping multiple groups for `coder-admins` and `coder-users`.

Updated details:
- Differentiated between `group-sync` and `role-sync` settings.
- Added a prompt for using premium licenses for organization-level sync.

New UI screenshots for added clarity:
- Added `group-sync.png` and `role-sync.png` for visual guidance.
@bpmct bpmct marked this pull request as ready for review September 29, 2024 22:48
@bpmct
Copy link
Member Author

bpmct commented Sep 29, 2024

All set, ready for review @Emyrk @mattvollmer @EdwardAngert!

- Deleted submodules 'asdsadas' and 'data-takehome'.
- Improved JSON formatting for clarity.
- Refined UI text for better guidance on creating provisioners.
Correct the path to the licensing document in the organizations guide to ensure proper navigation for users.
- Refine description to include "Premium" in feature availability.
- Adjust terminology in auth and sync sections for consistency.
- Modify organization documentation to reflect unified naming.
@bpmct bpmct requested review from Emyrk and jaaydenh September 30, 2024 22:08
bpmct added 3 commits October 1, 2024 10:03
- Remove outdated reference to free usage.
- Add link to new Premium plan blog post for existing customers.
Clarified sentences by combining related information, making it easier to understand the options for exploring Premium features.
Copy link
Collaborator

@stirby stirby left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, added some minor comments

bpmct and others added 5 commits October 1, 2024 16:06
Switch the `state` property in documentation manifest entries from
single strings to arrays across all relevant fields for consistency.
This aligns the JSON structure, allowing multiple states to be clearly
defined when necessary and ensures future flexibility in state assignments.
@stirby stirby merged commit d04eaf8 into main Oct 1, 2024
29 of 30 checks passed
@stirby stirby deleted the orgs-licenses branch October 1, 2024 17:34
@github-actions github-actions bot locked and limited conversation to collaborators Oct 1, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
multi-org temporary label for multiple organizations related work
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants