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. |
secrets |
secrets::/ | Control certificate and key management. |
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. |
subnetpool |
subnetpool::/ | Control access to and behavior of sunbet pools. |
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 namespacetest
,sandbox
, andprod
(production) are namespaces at the next level.test
andsandbox
have sub-namespaces for usersprod
has sub-namespaces forsupport
,hr
, andretail
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
matchesjob::/prod/foo::job1
andjob::/prod/foo/bar::job1
. -
The realm
job::/prod/+::job1
matchesjob::/prod/test::job1
but notjob::/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
.