Skip to content

Commit

Permalink
Refine, Update operator porting interface and doc
Browse files Browse the repository at this point in the history 
Signed-off-by: Tyler Gu <jiaweig3@illinois.edu>
  • Loading branch information
@tylergu
tylergu committed Dec 17, 2023
1 parent 91bf242 commit 251b1ba
Show file tree
Hide file tree
Showing 2 changed files with 145 additions and 17 deletions.
25 changes: 19 additions & 6 deletions acto/lib/operator_config.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,13 @@ class ApplyStep(BaseModel, extra="forbid"):
"""Configuration for each step of kubectl apply"""
file: str = Field(
description="Path to the file for kubectl apply")
operator: Optional[bool] = Field(
operator: bool = Field(
description="If the file contains the operator deployment",
default=False)
namespace: Optional[str] = Field(
description="Namespace for applying the file, if not specified," +
"use the namespace in the file or Acto namespace",
description="Namespace for applying the file. If not specified, " +
"use the namespace in the file or Acto namespace. " +
"If set to null, use the namespace in the file",
default=DELEGATED_NAMESPACE)


Expand Down Expand Up @@ -44,7 +45,7 @@ class DeployConfig(BaseModel, extra="forbid"):
"""Configuration for deploying the operator"""
steps: List[DeployStep] = Field(
description="Steps to deploy the operator",
min_items=1,)
min_length=1,)


class AnalysisConfig(BaseModel, extra="forbid"):
Expand All @@ -57,7 +58,8 @@ class AnalysisConfig(BaseModel, extra="forbid"):
package: str = Field(
description="Package name in which the type of the CR is defined")
entrypoint: Optional[str] = Field(
description="The relative path of the main package for the operator")
description="The relative path of the main package for the operator, " +
"required if the main is not in the root directory")


class KubernetesEngineConfig(BaseModel, extra="forbid"):
Expand All @@ -81,7 +83,7 @@ class OperatorConfig(BaseModel, extra="forbid"):
collect_coverage: bool = False
custom_oracle: Optional[str] = Field(
default=None, description="Path to the custom oracle file")
diff_ignore_fields: List[str] = Field(default_factory=list)
diff_ignore_fields: Optional[List[str]] = Field(default_factory=list)
kubernetes_version: str = Field(
default="v1.22.9", description="Kubernetes version")
kubernetes_engine: KubernetesEngineConfig = Field(
Expand All @@ -104,3 +106,14 @@ class OperatorConfig(BaseModel, extra="forbid"):
default=None, description="Path to the context file")
focus_fields: Optional[List[List[str]]] = Field(
default=None, description="List of focus fields")


if __name__ == "__main__":
import json

import jsonref
print(
json.dumps(
jsonref.replace_refs(
OperatorConfig.model_json_schema()),
indent=4))
137 changes: 126 additions & 11 deletions docs/port.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,136 @@ To port a new operator to Acto and test it, users would need to create a configu
The minimum requirement for Acto to test an operator is to provide a way to deploy the operator.

Acto supports three different ways for specifying the deployment method: YAML, Helm, and Kustomize.
(Helm and Kustomize is lacking support right now, please first use YAML)
To specify operators' deployment method in a YAML way, users need to bundle all the required
resources into a yaml file, e.g. Namespace, ClusterRole, ServiceAccount, and Deployment.
resources into a YAML file, e.g. Namespace, ClusterRole, ServiceAccount, and Deployment.

After aggregating the required resources into a file
Then, specify the deployment in the configuration file through the `deploy` property, e.g.:
Deploying operator can be expressed as a sequence of steps to be applied through
the `deploy` property.
For example, to deploy the cass-operator, we need to first apply the `init.yaml`
which deploys the cert-manager required by the cass-operator,
and then apply the `bundle.yaml` which contains all the required resource
definitions for deploying the cass-operator.
The `deploy` property would be written as:
```json
{
"deploy": {
"method": "YAML",
"file": "data/cass-operator/bundle.yaml",
"init": "data/cass-operator/init.yaml"
}
"deploy": {
"steps": [
{
"apply": {
"file": "data/cass-operator/init.yaml",
"namespace": null
}
},
{
"wait": {
"duration": 10
}
},
{
"apply": {
"file": "data/cass-operator/bundle.yaml",
"operator": true
}
}
]
}
```

<details>
<summary>*JsonSchema* for the `deploy` property</summary>

```json
"deploy": {
"additionalProperties": false,
"description": "Configuration for deploying the operator",
"properties": {
"steps": {
"description": "Steps to deploy the operator",
"items": {
"additionalProperties": false,
"properties": {
"apply": {
"allOf": [
{
"additionalProperties": false,
"description": "Configuration for each step of kubectl apply",
"properties": {
"file": {
"description": "Path to the file for kubectl apply",
"title": "File",
"type": "string"
},
"operator": {
"default": false,
"description": "If the file contains the operator deployment",
"title": "Operator",
"type": "boolean"
},
"namespace": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "__DELEGATED__",
"description": "Namespace for applying the file. If not specified, use the namespace in the file or Acto namespace. If set to null, use the namespace in the file",
"title": "Namespace"
}
},
"required": [
"file"
],
"title": "ApplyStep",
"type": "object"
}
],
"default": null,
"description": "Configuration for each step of kubectl apply"
},
"wait": {
"allOf": [
{
"additionalProperties": false,
"description": "Configuration for each step of waiting for the operator",
"properties": {
"duration": {
"default": 10,
"description": "Wait for the specified seconds",
"title": "Duration",
"type": "integer"
}
},
"title": "WaitStep",
"type": "object"
}
],
"default": null,
"description": "Configuration for each step of waiting for the operator"
}
},
"title": "DeployStep",
"type": "object"
},
"minItems": 1,
"title": "Steps",
"type": "array"
}
},
"required": [
"steps"
],
"title": "DeployConfig",
"type": "object"
}
```
</details>

### Providing the name of the CRD to be tested
Specify the name of the CRD to be tested in the configuration through the `crd_name` property. Only required if the operator defines multiple CRDs.
Specify the name of the CRD to be tested in the configuration through the `crd_name` property.
Only required if the operator defines multiple CRDs.
E.g.:
```json
{
Expand All @@ -33,7 +146,9 @@ E.g.:
```

### Providing a seed CR for Acto to start with
Provide a sample CR which will be used by Acto as the seed. This can be any valid CR, usually operator repos contain multiple sample CRs. Specify this through the `seed_custom_resource` property in the configuration.
Provide a sample CR which will be used by Acto as the seed.
This can be any valid CR, usually operator repos contain multiple sample CRs.
Specify this through the `seed_custom_resource` property in the configuration.

### Providing source code information for whitebox mode (optional)
Acto supports a whitebox mode to enable more accurate testing by utilizing source code information.
Expand Down

0 comments on commit 251b1ba

Please sign in to comment.