Core Concepts
On This Page:
Configurations objects
All configuration and infrastructure is represented as objects. These objects behave as REST resources from public API point of view. Most of the objects support CRUD operations and REST API. Some of the objects may be implicit and may only be visible or configurable via custom REST API(s)
All objects have three main parts:
- Metadata is data provided by user. Some of it is immutable and can only be provided during create. E.g name.
- System metadata is data allocated by system, that cannot be changed by user. E.g. UUID of the object, Owner, Creator ID, etc.
- Spec is data that actually defines the desired state of the object and has a feature specific shape.
Every object optionally has one or more status objects. As different parts of the system process these objects, they may generate status.
There is a concept of a “kind” of an object. In programing languages, “type” of an object is “kind” and “shape” together. However, “kind” is similar to type but without a shape. Different services in the system may have different “shape” but the same “kind”. For example, “site” is a kind of an object, but the shape of a site may change in different services. “Create shape” of site object may differ from “Replace shape”.
Most objects will have three shapes for specs, and they may differ:
- Create spec
- Replace spec
- Get spec
Tenant
Tenant is an entity that is the owner of a given set of configuration and infrastructure. Tenant is the owner of all configuration objects that a user with given tenant-id has created. Tenant is fundamental concept of isolation, and a tenant cannot access any objects or infrastructure of other tenants.
There is a special tenant “ves.io” representing F5® Distributed Cloud Services. “ves.io” does not have any special privileges, it is the same as any other tenant. However, “ves.io” is the owner of all the F5 Distributed Cloud infrastructure and it shares this infrastructure with other tenants. There are two types of tenants - individual tenants and enterprise tenants and depending on your sign-up, tenant type and identifier will be assigned by the system automatically. Enterprise tenant can have multiple users with RBAC roles while individual tenant has only one user.
Namespaces
Tenant’s configuration objects are grouped under namespaces. Namespaces can be thought of as administrative domains. All the objects of the same kind need to have unique names in a given namespace. Namespace themselves must be unique within a tenant. In this document namespace will be referred as <tenant>/<namespace>, which will be globally unique.
Every object’s unique identity is {kind,tenant,namespace,name}. This is called fully qualified name(FQN) of the object. When a user or other objects refers to an object, FQN is required. Many times the tenant field can be omitted as it is derived from login credentials. So tenants usually refer to objects as {kind, namespace, object}.
A namespace is a concept of isolation within a tenant. An object within one namespace cannot be referred by another namespace, except for a special namespace called “shared”. Namespaces can be used to isolate different application teams like finance, marketing, etc. It can also be used to isolate deployments like production, staging, test, etc. Most of the APIs, especially monitoring APIs, are scoped by namespace. Currently for scaling concerns, cross namespace List APIs are not supported.
When a new tenant is created, following namespaces are automatically created for a tenant:
-
system - all the infrastructure objects are in system namespace, like sites, networks, interfaces. Site objects in infrastructure are special as they are visible to all namespaces within the tenant. “system” namespace cannot be deleted.
-
shared - objects in this namespace are visible to all namespaces within the tenant. “shared” namespace cannot be deleted.
-
default - default is a regular namespace and created at tenant's inception, as a convenience to tenants.
-
ves-io-shared - this is a placeholder namespace and represents “shared” namespace of tenant “ves.io” (“ves-io/shared'' is shared with all tenants). This namespace can only be used to perform “GET” operations by the tenants. The placeholder namespace is needed as users cannot access ves-io/shared namespace directly as tenant is decided by credentials,
Namespace is sometimes used in domain names to uniquify the FQDN. As a result, namespace have to follow DNS label format - https://tools.ietf.org/html/rfc1035.
Details on all the parameters that can be configured for this object is covered in the API specification.
References
When an object refers to other objects, reference needs to be FQN of the other object. For convenience, a short reference (partially qualified name) can also be given, and it will be converted to FQN by the system. If object O1(referee) refers to O2(referred) then following rules are followed:
- If reference is {kind, O2} → {kind, O1’s tenant, O1’s namespace, O2}
- If reference is {kind, ns, O2} → {kind, O1’s tenant, ns, O2}
Since (currently) everything is scoped by tenant and namespace, only reason one may need to give tenant and namespace is when referring to objects from tenant/shared and ves-io/shared. However, it is always a good practice to use FQN for references.
Labels
Labels are meta attributes of the configuration objects. Labels can be used to do arbitrary classification of objects. Conceptually there are no restrictions on what labels you can add to an object.
Labels are made of two parts “key ” and “value”. They are represented as “key=value” or “key(value)”.
Examples
- region=sf-bay-area, region(nyc-metro)
- deployment=production, deployment(staging)
- application=my-app, application(your-app)
In above example region, deployment and application are keys, sf-bay-area, nyc-metro, production, staging, my-app and your-app are values
If above labels were applied to site objects, then the following sets can be created:
- All sites in nyc-metro area : expression sites in “region in ( nyc-metro)”
- All sites in nyc-metro or sf-bay-area : expression sites in the “region in (nyc-metro, sf-bay-area)’
- All sites that are production and in sf-bay-area : expression sites in the “region in (sf-bay-area) and deployment in (production)”
Label Expressions
Label expressions are used as “label selector expression” for selection of a set of objects. Label selectors are used in an object’s data-model to refer to dynamic set of other objects instead of hard references. For example, all sites to advertise VIP of virtual host, all endpoints to match in security policy, all endpoints to discover, all sites for application deployment, etc. It is a mechanism to create arbitrary subsets. Labels expressions can also be used as query parameters in list APIs
Any string that satisfies a label format can be used as labels on the objects. However, all labels are not the same. There are three types of labels:
-
Known Labels - Known labels are labels that are defined a-priori (before use). Known labels need to have known keys.
-
Implicit Labels - Implicit labels are implicit property of the object that can be used in policy language but cannot be assigned to objects. Currently, the only implicit label that is supported is geo-ip information for a client (it’s public ip address on the internet). Implicit labels are specific in their use - for example, geo-ip implicit labels are supported only for public ip in the context of service policy or network policy.
-
Custom Labels - Labels that are assigned to objects on the fly with defining them on demand.
Known Keys and Known Labels
For consistency in labeling, it might be advantageous to advertise what labels to use. So there is the concept of known keys and known labels. These are implicit objects that can be configured in shared namespace of tenant so that other users can use these in a consistent way. Known keys are keys that can be used with user defined values. Known labels is a key-value pair that can be attached to objects.
Key are strings with format <key prefix>/<key>. Key prefix is usually domain names and is optional. Key follows DNS label format. For example, all F5 Distributed Cloud Services keys start with key prefix “ves.io”. Key = “ves.io/region''.
Labels are always of DNS label format.https://tools.ietf.org/html/rfc1035.
All F5 Distributed Cloud Services values are prefixed with “ves-io-”. E.g “ves.io/region=ves-io-sf-bay-area". Users are prevented from using “ves.io” key prefix and “ves-io-” value prefix.
Known keys and known labels available in “ves.io/shared” namespace are accessible by all tenants and can be used by everyone.