Identifying Cluster Resources

Central to authoring policies is a system for referring to cluster resources unambiguously and at the appropriate level of granularity. Apcera provides you with an intuitive mechanism for quickly identifying resources in your cluster and applying policy to them.

See Policy Language Syntax and Policy Permissions for reference.

Fully-qualified name (FQN)

Every resource in an Apcera cluster (job, package, service, etc.) has a fully-qualified name (FQN). For example, the FQN for a job named foo deployed in the prod/retail namespace is job::/prod/retail::foo.

The FQN is a 3-part structure for categorizing entities in the system. The FQN represents a hierarchy of resource type, namespace, and local name. Each part is separated by a double-colon (::). All parts are comprised of tokens. ResType is a single token. Namespace and LocalName may have multiple tokens, with each token separated by a forward-slash ('/').

The FQN is written as a string in the following form:

ResType::/Namespace[/Namespace...]::LocalName[/LocalName...]

Where:

• Resource type identifies the kind of resource (jobs, packages, services, etc.).

• Namespace locates the resource in the hierarchy. It is used, among other things, for policy and permission control.

• Local name provides a unique identifier within the namespace.

You can represent a collection of resources (called a realm) by omitting the local name or using the root namespace. This can be useful in writing policies that refer to multiple resources.

Resource Types

Every resource in the cluster belongs to one of the resource types listed below. There is a root realm corresponding to each resource type that you use to author policy rules for controlling access to and use of resources of that type.

Resource Type	Realm	Description
audit	audit::/	Control access to the audit log in the web console.
auth	auth::/	Control Auth Server token issuance and lifetime, trusts with identity providers, minimum auth requirements for obtaining a token, setting token name.
cluster	cluster::/	Control access to cluster details and Instance Manager monitoring in the web console.
gateway	gateway::/	Control the behavior of service gateways.
job	job::/	Control app and workload behavior (particularly during initialization and resource allocation)
network	network::/	Control ability to create and join virtual networks.
package	package::/	Control source and package behavior (particularly during creation and consumption in a job).
policy	policy::/	Control policy authoring (read/edit).
policydoc	policydoc::/	Control policy document administration (CRUD).
principal	principal::/	Name of claim issuer. Reserved for internal use.
provider	provider::/	Control access to and registration of providers.
quota	quota::/	Control resource limits on a per-namespace basis.
route	route::/	Control URLs and protocols for a route to an app or service.
sempiperule	sempiperule::/	Control behavior of semantic pipelines
service	service::/	Control access to and creation of services such as databases and APIs.
stagpipe	stagpipe::/	Control access to and behavior of staging pipelines.

Namespaces

Every user has a default namespace, similar to a home directory in a file system. The default namespace for a user is /sandbox/[userName].

Namespaces create the address space for system and user-defined resources. You can organize resources in a namespace as if they were files in a file system.

Namespaces are hierarchical for each resource type, starting with the root, /. For example:

/

/test
/test/[username]

/sandbox
/sandbox/[username]

/prod
/prod/support
/prod/support/[username]
/prod/hr
/prod/retail

In the above block:

• / is the root namespace
• test, sandbox, and prod (production) are namespaces at the next level.
• test and sandbox have sub-namespaces for users
• prod has sub-namespaces for support, hr, and retail
• support has sub-namespaces for users

FQN examples for policy realm matching

FQNs are used to identify the resources against which to apply policy. In this context the FQN is used by the policy engine as a string matcher.

Realm match hierarchy

The realm match is done with preference to the namespace depth first, then the local name depth, with the most specific from a path perspective taking precedence.

If you have policy realms that have similar path origins, the realm with the deepest namespace path is preferred. If all matches have the same namespace depth, the realm with the deepest local name is preferred.

Thus, in the following set of policies, the latter policy takes precedence ("wins") because of its deeper namespace depth.

quota::/dev {
    { max.job.memory 64GB }
    { max.instance.memory 32GB }
}

quota::/dev/proj1 {
    { max.job.memory 128GB }
}

And, if you were to add the following policy, it would take precedence over 128GB quota specified for quota::/dev/proj1 realm because the local name is specified:

quota::/dev/proj1::test {
    { max.job.memory 256GB }
}

The phrase "preference to the namespace depth" means that the closest namespace match will take precedence when two policies are in conflict. In the case of a quota, you cannot have a max.job.memory of 32GB AND 128GB (it should only be one of those). Thus, in the above example, the policy that will be applied to a job created in the /dev/proj1 namespace will be the policy that matches that namespace and the quota should be set to 128GB.

Note that max.instance.memory 32GB will still be applied to job instances in the /dev/proj1 realm by way of inheritance. Thus, jobs in the /dev/proj1 will have quota limits of 128GB per job (per policy 2) and 32GB per instance (per policy 1). Note that writing policies in this fashion is not recommended, and these examples are provided for illustration purposes only to explain how the policy language works.

Match wildcards

To match resources, you can use the asterisk (*) as a wildcard and the plus sign (+) as a single token wildcard.

The following examples explain the use of these special symbols in context of valid and invalid FQNs for realmset matching.

Valid wildcard FQNs

The following examples are valid wildcard FQNs.

job::/
job::/prod
job::/*
job::/prod/retail
job::/prod/*
job::/::job1
job::/::job1/*
job::/prod::job1
job::/prod::job1/*
job::/prod/*::job1
job::/prod/*::job1/*
job::/+/+
job::/+/[user]/bob
job::/*/bob/*/betty

Invalid FQNs

The following examples are invalid wildcard FQNs, with explanation.

job::prod                                          	// Missing slash before prod
job::/*/*                                           // Path element of “*” cannot be followed by “*”, “+”, or “$”
job::/*/+                                           // Path element of “*” cannot be followed by “*”, “+”, or “$”
job::/*/[user]/bob    								// Path element of “*” cannot be followed by templated value [`[user]`]

Wildcard examples

Consider the following additional examples for using wildcards:

• The realm job::/prod/*::job1 matches job::/prod/foo::job1 and job::/prod/foo/bar::job1.

• The realm job::/prod/+::job1 matches job::/prod/test::job1 but not job::/prod/test/bar::job1.

Note, however, the following wildcard behavior:

• The realm job::/prod/ applies to all jobs in the /prod namespace, as well as all jobs in any descendent namespace, such as /prod/web/ and /prod/web/user/.

• However, the wildcard realm job::/prod/* only applies to descendent namespaces, such as /prod/web/ and /prod/web/user. It does not match on any jobs in the /prod namespace.

Exact resource match

You can also use the dollar sign ($) to instruct the FQN parser to not match the FQN if there is a descendent “level.”

If necessary you can perform an exact resource match using the $ character. The $ instructs the parser to stop matching at the specified level.

For example, the realm declaration job::/arapce/prodccc/+/$ matches job::/arapce/prodccc/web but does not match job::/arapce/prodccc/web/A.