docs: HCP organization "owner" role changes #1150

boruszak · 2025-10-21T20:36:23Z

Description

This PR updates HCP platform documentation. Previously, an organization supported a single non-transferrable owner. To better support business continuity, organizations now allow up to 3 users with the owner role. These owners can be added or removed as desired, although one user must always be an owner for the organization.

Preview links

github-actions · 2025-10-21T20:38:56Z

Vercel Previews Deployed

Name	Status	Preview	Updated (UTC)
Dev Portal	✅ Ready (Inspect)	Visit Preview	Mon Oct 27 23:38:12 UTC 2025
Unified Docs API	✅ Ready (Inspect)	Visit Preview	Mon Oct 27 23:32:11 UTC 2025

github-actions · 2025-10-21T20:56:55Z

Broken Link Checker

No broken links found! 🎉

xargs-P

Thank you VERY much @boruszak . I can see you skills throughout the edits 😄
I added a few comments I wanted your feedback on.

content/hcp-docs/content/docs/hcp/admin/orgs.mdx

content/hcp-docs/content/docs/hcp/admin/projects/index.mdx

content/hcp-docs/content/docs/hcp/iam/access-management.mdx

xargs-P

Looking good!! I think we are ready to merge once the code is ready to go 🙏

aimeeu

I left some style nits :)

aimeeu · 2025-10-29T11:07:42Z

content/hcp-docs/content/docs/hcp/admin/projects/index.mdx

-
-   </Note>
+   organization. If you have logged in before, the portal opens the last project you were in.
+   Navigate to the Organization to change projects


Suggested change

Navigate to the Organization to change projects

Navigate to the Organization to change projects.

missing period

aimeeu · 2025-10-29T11:10:12Z

content/hcp-docs/content/docs/hcp/admin/projects/index.mdx

 ![HCP Organization Structure](/img/docs/hcp-core/diagram-hcp_organization_project-resources.png)

-A resource is any item that the access management system controls access to. Examples of resources are a HCP Vault Dedicated cluster, HCP Packer Bucket, HashiCorp Virtual Network (HVN) or a HCP Vault Secret App.   The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If an resource exists, HCP will block users from deleting the project. This page helps you to identify what resources are still in the project.
+A resource is any item that the access management system controls access to. Examples of resources are a HCP Vault Dedicated cluster, HCP Packer Bucket, or a HashiCorp Virtual Network (HVN). The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If an resource exists, HCP will block users from deleting the project. This page helps you to identify what resources are still in the project.


Suggested change

A resource is any item that the access management system controls access to. Examples of resources are a HCP Vault Dedicated cluster, HCP Packer Bucket, or a HashiCorp Virtual Network (HVN). The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If an resource exists, HCP will block users from deleting the project. This page helps you to identify what resources are still in the project.

A resource is any item that the access management system controls access to. Examples of resources are an HCP Vault Dedicated cluster, an HCP Packer Bucket, or a HashiCorp Virtual Network (HVN). The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If a resource exists, HCP blocks users from deleting the project. This page helps you to identify what resources are still in the project.

nit: indefinite article should be "an" for HCP (an HCP Vault...)

aimeeu · 2025-10-29T11:12:59Z

content/hcp-docs/content/docs/hcp/admin/orgs.mdx

+[HCP projects](/hcp/docs/hcp/admin/projects), which separate access to resources such as [HashiCorp Virtual Networks (HVN)](/hcp/docs/hcp/network) according to [user permissions](/hcp/docs/iam/users#user-permissions). An organization can have up to 100 projects.

-Users can be a member of multiple organizations if invited by the admin of other organizations. However, you can only create and own one organization for your HCP account.
+Users can be a member of multiple organizations, and organizations can have a maximum of 3 users with the `owner` role. You can add and delete organization owners over time, but organizations require at least 1 owner at all times.


Suggested change

Users can be a member of multiple organizations, and organizations can have a maximum of 3 users with the `owner` role. You can add and delete organization owners over time, but organizations require at least 1 owner at all times.

Users can be a member of multiple organizations, and organizations can have a maximum of three users with the `owner` role. You can add and delete organization owners over time, but organizations require at least one owner at all times.

nit: spell out numbers zero through nine

aimeeu · 2025-10-29T11:15:38Z

content/hcp-docs/content/docs/hcp/admin/orgs.mdx

+
+## Find organization owners
+
+An organization can have 1-3 users with the `owner` role. Owners can change, but there must always be at least 1 owner per organization.


Suggested change

An organization can have 1-3 users with the `owner` role. Owners can change, but there must always be at least 1 owner per organization.

An organization can have one to three users with the `owner` role. Owners can change, but there must always be at least one owner per organization.

style nit number ranges

aimeeu · 2025-10-29T11:17:02Z

content/hcp-docs/content/docs/hcp/admin/orgs.mdx

+
+An organization can have 1-3 users with the `owner` role. Owners can change, but there must always be at least 1 owner per organization.
+
+To find the organization's current owners:


Suggested change

To find the organization's current owners:

To find the organization's current owners, perform the following steps:

aimeeu · 2025-10-29T11:19:24Z

content/hcp-docs/content/docs/hcp/iam/access-management.mdx

 @include '/hcp-administration/assign-project-role.mdx'

-# Role Names and Role IDs
+## Role Names and Role IDs


Suggested change

## Role Names and Role IDs

## Role names and role IDs

aimeeu · 2025-10-29T11:20:22Z

content/hcp-docs/content/docs/hcp/iam/users.mdx


 @include '/hcp-administration/permission-intro.mdx'

 ## Access Management


Suggested change

## Access Management

## Access management

aimeeu · 2025-10-29T11:21:21Z

content/hcp-docs/content/partials/hcp-administration/permission-intro.mdx

@@ -1,16 +1,15 @@
-HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the specific HCP application documentation for more information.
+HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the individual HCP service's documentation for more information.


Suggested change

HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the individual HCP service's documentation for more information.

HCP uses a role-based access control (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the individual HCP service's documentation for more information.

aimeeu · 2025-10-29T11:22:24Z

content/hcp-docs/content/partials/hcp-administration/permission-intro.mdx

 ### Inheritance
-Each resource in a HCP organization has an IAM policy associated with it that informs about the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource. 
+
+Each resource in a HCP organization has an IAM policy associated with it that sets the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource.


Suggested change

Each resource in a HCP organization has an IAM policy associated with it that sets the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource.

Each resource in an HCP organization has an IAM policy associated with it that sets the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource.

aimeeu · 2025-10-29T11:23:10Z

content/hcp-docs/content/partials/hcp-administration/permission-intro.mdx

+For example, a user assigned the `viewer` role in an organization also has `viewer` role permissions for projects within the organization. Similarly, a user assigned the `contributor` role in a project also has `contributor` role permissions for resources within the project.

-If a user has an `viewer` role in an organization and `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project.   
+If a user has an `viewer` role in an organization and `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project.


Suggested change

If a user has an `viewer` role in an organization and `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project.

If a user has a `viewer` role in an organization and an `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project.

boruszak added 3 commits October 20, 2025 14:50

orgs page

fc4c773

Updates

6c5990a

Owner role ID for table

3d6ef53

github-actions bot added HCP HCP Docs labels Oct 21, 2025

boruszak added the documentation Improvements or additions to documentation label Oct 21, 2025

boruszak marked this pull request as ready for review October 21, 2025 22:01

boruszak requested review from a team as code owners October 21, 2025 22:01

boruszak requested review from Younique98 and neatchu October 21, 2025 22:01

Younique98 approved these changes Oct 21, 2025

View reviewed changes

Merge branch 'main' into docs/CE-1060-add-change-organization-owners

cc4ee44

xargs-P requested changes Oct 22, 2025

View reviewed changes

content/hcp-docs/content/docs/hcp/admin/orgs.mdx Show resolved Hide resolved

content/hcp-docs/content/docs/hcp/admin/projects/index.mdx Outdated Show resolved Hide resolved

content/hcp-docs/content/docs/hcp/iam/access-management.mdx Outdated Show resolved Hide resolved

boruszak and others added 2 commits October 27, 2025 16:14

Changes from review

35061c2

Merge branch 'main' into docs/CE-1060-add-change-organization-owners

4f48743

xargs-P approved these changes Oct 27, 2025

View reviewed changes

boruszak removed the HCP label Oct 28, 2025

aimeeu reviewed Oct 29, 2025

View reviewed changes

	Navigate to the Organization to change projects
	Navigate to the Organization to change projects.

	Users can be a member of multiple organizations, and organizations can have a maximum of 3 users with the `owner` role. You can add and delete organization owners over time, but organizations require at least 1 owner at all times.
	Users can be a member of multiple organizations, and organizations can have a maximum of three users with the `owner` role. You can add and delete organization owners over time, but organizations require at least one owner at all times.


		## Find organization owners

		An organization can have 1-3 users with the `owner` role. Owners can change, but there must always be at least 1 owner per organization.

	An organization can have 1-3 users with the `owner` role. Owners can change, but there must always be at least 1 owner per organization.
	An organization can have one to three users with the `owner` role. Owners can change, but there must always be at least one owner per organization.


		An organization can have 1-3 users with the `owner` role. Owners can change, but there must always be at least 1 owner per organization.

		To find the organization's current owners:


		@include '/hcp-administration/permission-intro.mdx'

		## Access Management

		@@ -1,16 +1,15 @@
		HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the specific HCP application documentation for more information.
		HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the individual HCP service's documentation for more information.

	HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the individual HCP service's documentation for more information.
	HCP uses a role-based access control (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the individual HCP service's documentation for more information.

	Each resource in a HCP organization has an IAM policy associated with it that sets the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource.
	Each resource in an HCP organization has an IAM policy associated with it that sets the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource.

	If a user has an `viewer` role in an organization and `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project.
	If a user has a `viewer` role in an organization and an `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project.

docs: HCP organization "owner" role changes #1150

Are you sure you want to change the base?

docs: HCP organization "owner" role changes #1150

Uh oh!

Conversation

boruszak commented Oct 21, 2025

Description

Preview links

Uh oh!

github-actions bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vercel Previews Deployed

Uh oh!

github-actions bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Broken Link Checker

Uh oh!

xargs-P left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xargs-P left a comment

Choose a reason for hiding this comment

Uh oh!

aimeeu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Oct 21, 2025 •

edited

Loading

github-actions bot commented Oct 21, 2025 •

edited

Loading