Status: In Progress

Sponsor User: IBM

Date of Submission: 12 Sep 2022 

Submitted by: David Booz (booz@us.ibm.com)

Affiliation(s): IBM

<Please fill out the above fields, and the Overview, Design and User Experience sections below for an initial review of the proposed feature.>

Scope and Signoff: (to be filled out by Chair)

Overview

<Briefly describe the problem being solved, not how the problem is solved, just focus on the problem. Think about why the feature is needed, and what is the relevant context to understand the problem.>

...

A new built-in node property called openhorizon.kubernetesNamespace is introduced, the value reflects the namespace in which the agent is installed. This property is read-only, it is always set by the OH runtime and is not settable by any user role. This property MAY be used in a deployment or policy constraint expression.

Service Definition:

There are no updates to the service definition schema.

Deployment:

When an edge cluster service is deployed, by default, it is deployed into the same namespace as the agent/node.

...

A new field is added to the service section of a deployment policy, indicating the target namespace for the deployment. This namespace overrides a namespace definition in the operator definition of an edge cluster service.

"service": { ...
   "cluster_namespaceclusterNamespace": <string>
}

This field is optional and ignored for services deployed to a device.

...

For namespace scoped nodes, this field acts as a built-in constraint that causes namespace scoped nodes in namespaces other than the one specified by this field to be eliminated as deployment targets. Effectively, this field acts as a built-in constraint ANDed to the user specified constraint expression. The deploycheck CLI MUST detect this case.

In the absence of the "cluster_namespaceclusterNamespace" field, a namespace definition embedded in the operator definition acts as a built-in constraint that causes namespace scoped nodes in namespaces other than embedded namespace definition to be eliminated as deployment targets. Effectively, the embedded namespace definition acts as a built-in constraint ANDed to the user specified constraint expression. The deploycheck CLI MUST detect this case.

There could be a semantic conflict if the deployer specifies a "cluster_namespaceclusterNamespace" and uses openhorizon.kubernetesNamespace in a constraint expression. It is likely that such a policy will result in no deployments, which would be the technically correct behavior but it might also be surprising to the user. This is why the hzn deploycheck command exists, to help the user understand semantic mismatches in deployment policy. The deploycheck command MUST detect whether or not there is a real semantic conflict in this case.

...

1. An edge cluster node with cluster privileges is chosen as a deployment target by the policy's constraint expression. The deployment policy has no "cluster_namespaceclusterNamespace" defined and no embedded namespace definition. The edge service is deployed in the openhorizon-agent namespace.
2. An edge cluster node with cluster privileges is chosen as a deployment target by the policy's constraint expression. The deployment policy has "cluster_namespaceclusterNamespace":"ABC". The edge service is deployed in the ABC namespace.
3. An edge cluster node with cluster privileges is chosen as a deployment target. The deployment policy has no "cluster_namespaceclusterNamespace" defined. The edge service has an embedded namespace definition for XYZ. The edge service is deployed in the XYZ namespace.
4. An edge cluster node with cluster privileges is chosen as a deployment target. The deployment policy has "cluster_namespaceclusterNamespace":"ABC" defined. The edge service has an embedded namespace definition for XYZ. The edge service is deployed in the ABC namespace.

...

1. A node in namespace ABC. The deployment policy has "cluster_namespaceclusterNamespace":"ABC". The edge service is deployed to the node.
2. A node in namespace ABC. The deployment policy has no "cluster_namespaceclusterNamespace". The edge service is deployed to the node.
3. A node in namespace ABC. The deployment policy has no "cluster_namespaceclusterNamespace". The deployment policy has a constraint expression openhorizon.kubernetesNamespace=XYZ. The edge service is NOT deployed to the node.
4. A node in namespace ABC. The deployment policy has "cluster_namespaceclusterNamespace":"ABC". The deployment policy has a constraint expression openhorizon.kubernetesNamespace=XYZ. The edge service is NOT deployed to the node. The user received a warning when publishing the policy that the policy might result in no service deployments.

Note: The node owner is always free to configure a deployment constraint expression that limits the namespace

...

1. .

Pattern:

A new field is added to the schema of a pattern (as a top level field in the schema), indicating the target namespace for the pattern's deployment.

 "namespaceclusterNamespace": <string>

The namespace "clusterNamespace" field is optional and ignored for patterns patterns deployed to a device. Namespace scoped nodes not in the specified namespace are not eligible to deploy the pattern. Cluster scoped nodes only deploy patterns that have an empty "clusterNamespace" field. A pattern with an empty "clusterNamespace" MUST NOT be deployed to a devicenamespace scoped node.

A namespace specified in the pattern overrides any namespace defined in the operator definition of all services in the pattern.

A pattern is in error if it attempts to deploy services to a namespace scoped node where the collection of services in the pattern are NOT deployable to the same namespace. Clearly this can only happen when the namespace "clusterNamespace" is NOT specified in the pattern definition but is contained within the operator definitionand one of the services contains an embedded namespace definition.

Node:

The node resource is also updated to contain the cluster namespace so that it is displayed in the node related CLI commands.

User Experience

<Describe which user roles are related to the problem AND the solution, e.g. admin, deployer, node owner, etc. If you need to define a new role in your design, make that very clear. Remember this is about what a user is thinking when interacting with the system before and after this design change. This section is not about a UI, it's more abstract than that. This section should explain all the aspects of the proposed feature that will surface to users.>

...

hzn exchange deployment addPolicy  -f <policy_definition>

If the policy specifies "cluster_namespaceclusterNamespace" and the property openhorizon.kubernetesNamespace is present in the constraint expression, a warning is provided telling the user that this deployment policy may result in no service deployment. The user will be directed to use the hzn deploycheck command to verify whether or not a deployment will result.

...

• a semantic conflict if the deployer specifies a "cluster_namespaceclusterNamespace" and uses openhorizon.kubernetesNamespace in a constraint expression
• deployment target selection (or not) in the absence of the "cluster_namespaceclusterNamespace" field, and a namespace definition embedded in the operator definition
• deployment target selection (or not) in the presence of the "cluster_namespaceclusterNamespace" field, and a namespace definition embedded in the operator definition
• correct deployment target selection as defined in the Deployment section above

hzn exchange service publish

If the service definition contains an embedded namespace definition, provide a warning to the user that due to the use that of an embedded namespace definition they are not following best practices and therefore the service might not be deployable. Use the hzn deploycheck command before this service is deployed to ensure that the policy will select nodes as expected.

hzn exchange pattern

External Components

<Describe any new or changed interactions with components that are not the agent or the management hub.>

...

The Exchange API is updated to support the new cluster_namespace clusterNamespace field in a deployment policy resource.

...

• Authoring edge cluster services: Add a note that packaging a namespace definition inside an operator definition is not considered a best practice. Service developers should allow deployers to choose the target namespace in the deployment policy.
• Deploying edge cluster services: Document the new cluster_namespace clusterNamespace field in the deployment policy, node and pattern. Describe how it's used and how it plays into the algorithm used by the Agbot to determine where edge cluster services are placed.
• Policy: Document the new built-in property openhorizon.kubernetesNamespace for edge node policies.
• Installing edge cluster agent: Document the new --namespace flag in the agent-install script.

...