Bug 1388415, added clarification around cluster roles

[ahardin-rh]

https://bugzilla.redhat.com/show_bug.cgi?id=1388415

[ahardin-rh]

@benjaminapetersen PTAL at my first draft

[benjaminapetersen]

Checking, pinging @enj for a look as well.

[enj]

Maybe xref to authorization.roles (did this get moved somewhere else)?

[enj]

I think this is the wrong approach. Copying an existing role is fine when you are testing things locally, but does not make sense when you actually intend to use that role. The user needs to build it from scratch so that they actually understand the permissions they are about to give out.

[ahardin-rh]

@enj Okay, thanks. What are the steps to do that?

[benjaminapetersen]

Heh, lots of work...

[benjaminapetersen]

@enj do you think its necessary to do a start from scratch example here?

[enj]

If you want documentation on how to create a custom role, then it really should start from scratch. Whether you want such documentation is up to you. Specifying all the valid options for each field would be a pain, but that is the only way the doc would actually be useful.

An example role with its important fields filled out:

apiVersion: v1
kind: Role
metadata:
  name: role_name
rules:
- apiGroups: null
  attributeRestrictions:
    apiVersion: v1
    kind: IsPersonalSubjectAccessReview
  resources:
  - localsubjectaccessreviews
  - subjectaccessreviews
  verbs:
  - create

The full Go specification:

// Role is a logical grouping of PolicyRules that can be referenced as a unit by RoleBindings.
type Role struct {
	unversioned.TypeMeta `json:",inline"`
	// Standard object's metadata.
	kapi.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

	// Rules holds all the PolicyRules for this Role
	Rules []PolicyRule `json:"rules" protobuf:"bytes,2,rep,name=rules"`
}

// PolicyRule holds information that describes a policy rule, but does not contain information
// about who the rule applies to or which namespace the rule applies to.
type PolicyRule struct {
	// Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule.  VerbAll represents all kinds.
	Verbs []string `json:"verbs" protobuf:"bytes,1,rep,name=verbs"`
	// AttributeRestrictions will vary depending on what the Authorizer/AuthorizationAttributeBuilder pair supports.
	// If the Authorizer does not recognize how to handle the AttributeRestrictions, the Authorizer should report an error.
	AttributeRestrictions kruntime.RawExtension `json:"attributeRestrictions,omitempty" protobuf:"bytes,2,opt,name=attributeRestrictions"`
	// APIGroups is the name of the APIGroup that contains the resources.  If this field is empty, then both kubernetes and origin API groups are assumed.
	// That means that if an action is requested against one of the enumerated resources in either the kubernetes or the origin API group, the request
	// will be allowed
	APIGroups []string `json:"apiGroups" protobuf:"bytes,3,rep,name=apiGroups"`
	// Resources is a list of resources this rule applies to.  ResourceAll represents all resources.
	Resources []string `json:"resources" protobuf:"bytes,4,rep,name=resources"`
	// ResourceNames is an optional white list of names that the rule applies to.  An empty set means that everything is allowed.
	ResourceNames []string `json:"resourceNames,omitempty" protobuf:"bytes,5,rep,name=resourceNames"`
	// NonResourceURLsSlice is a set of partial urls that a user should have access to.  *s are allowed, but only as the full, final step in the path
	// This name is intentionally different than the internal type so that the DefaultConvert works nicely and because the ordering may be different.
	NonResourceURLsSlice []string `json:"nonResourceURLs,omitempty" protobuf:"bytes,6,rep,name=nonResourceURLs"`
}

[enj]

Not sure why this is here.

[ahardin-rh]

@enj this was sourced from discussion in the BZ. I can remove this.

[ahardin-rh]

@enj @benjaminapetersen Updated. PTAL and let me know if we're getting closer. Thanks!

[benjaminapetersen]

Perhaps "We recommend you build it from scratch rather than copying an existing role".

@enj?

[ahardin-rh]

@enj @benjaminapetersen Updated. PTAL.

[benjaminapetersen]

@ahardin-rh will do, sorry for the delay, I've been OOO. Catching up soon.

[ahardin-rh]

@benjaminapetersen @enj PTAL. Thanks!

[benjaminapetersen]

Just built the docs so I could read them in context.

How often does the original Go source code end up in the docs? I'm thinking @enj posted that for our reference/discussion, but we should prob not include here. Reading it over and thinking a bit.

[enj]

Currently OOO. But yes, I never intended for the source code to be included. It was mostly there as a reference so that whatever YAML we included was thorough and correct.

[ahardin-rh]

@benjaminapetersen @enj Thank you! This is updated.

[benjaminapetersen]

Building again to check it out

[benjaminapetersen]

@ahardin-rh Had a few thoughts, made a PR to your branch a minute ago.

[ahardin-rh]

@benjaminapetersen Your updates and my edits are applied. PTAL. Thanks!

[xiaocwan]

here is a typo "clusterole", should be "clusterrole"

[xiaocwan]

This could be more or less confused to user, could add one comment here like "# To use current project:", or could combine this comand together with next line oc create -f path/to/localrole_exampleview.yaml -n <project_you_want_to_add_the_local_role_exampleview_to> .

[xiaocwan]

Also prefer a comment to explain this command here as above.

[xiaocwan]

should be "clusterrole_view.yaml" as above "> clusterrole_view.yaml"

[ahardin-rh]

Thumbs up, not thumbs down 👍 😄

[benjaminapetersen]

@jwforres fyi

[ahardin-rh]

@xiaocwan Many thanks. This is now updated. PTAL and let me know if I missed anything.

[xiaocwan]

@ahardin-rh LGTM now, thanks.

[ahardin-rh]

[rev_history]
|xref:../admin_guide/manage_authorization_policy.adoc#admin-guide-manage-authorization-policy[Managing Authorization Policies]
|Added clarifying details about cluster roles.
%
|xref:../architecture/additional_concepts/authorization.adoc#architecture-additional-concepts-authorization[Additional Concepts -> Authorization]
|Added clarifying details about cluster roles.
%