# agent-operator
This package is part of the OpenTestFactory initiative.
`agent-operator` is a Kubernetes operator. It allows for declaring pools of agents
on a Kubernetes cluster and for dynamical execution environment provisioning.
## Deployment
`agent-operator` can be deployed on a Kubernetes cluster using a Docker image [TBC],
or executed as a `kopf` script.
When deploying with Docker image, you may use sample `Deployment` and RBAC
definitions provided in the project `resources` directory. In the `Deployment` file,
you should set `ORCHESTRATOR_URL` environment variable value to
`{orchestrator_url}:{agentchannel_port}`.
When running as a `kopf` script (`kopf run main.py`), you should set the `ORCHESTRATOR_URL`
and `OPERATOR_CONTEXT` environment variables values respectively to
`{orchestrator_url}:{agentchannel_port}` and `local`.
## Overview
`agent-operator` monitors `Pool` resources. `CustomResourceDefinition` file and
sample `Pool` resource file are available in the project `resources`
directory. The operator supports Kubernetes namespaces, i.e. a `Pool` resource
can be applied in a specific namespace.
The `Pool` resource definition is as follows:
```yaml
apiVersion: agent.opentestfactory.org/v1alpha1
kind: Pool
metadata:
name: {resource name} # mandatory
spec:
poolSize: {agents pool size} # mandatory
tags: [list of agents tags] # mandatory
orchestratorSecret: {Kubernetes secret name}
namespaces: [list of orchestrator namespaces]
template: # mandatory
{execution pod definition}
```
`metadata.name` is the resource name.
`spec.poolSize` must be a positive integer or zero. It specifies the number of agents that
will be registered to the orchestrator when the resource is applied on a Kubernetes cluster.
`spec.tags` is a list of agent tags. All agents linked to a pool share the same tags.
`spec.orchestratorSecret` is a name of a Kubernetes secret holding the orchestrator token.
`spec.namespaces` is a list of orchestrator namespaces (not yet supported).
`spec.template` holds a pod template serving to provide dynamical execution environments.
### Pool Resource Monitoring
When a `Pool` resource definition file is applied to a cluster, the operator
registers `poolSize` agents with specified `tags` on the orchestrator. Registered
agents UUIDs are retrieved and stored as a list in the resource `status.create_agents.agents`
property, which also holds `resource_id` property, identifying the created resource.
This resource is then monitored for changes. The operator listens to the `spec.poolSize`
and `spec.tags` field updates. On pool size or tags update, if there are running
workflows and the update implies agents de-registration (namely changing tags or decreasing
pool size), the operator waits for their completion before applying the requested changes.
The resource `status.create_agents.agents` field is also updated.
When the operator is relaunched, it retrieves registered agents list from the orchestrator,
cleans up all busy agents and execution pods (as workflow won't be
able to successfully complete if the connection with the operator is interrupted), then
compares the resulting list to the `Pool` resource agents list and registers as many new agents
as needed.
When a `Pool` resource is deleted, the operator waits for all running workflows to be
completed before de-registering agents and allowing for resource deletion.
### Workflow Execution
The operator constantly queries agents to know their status. When an agent receives a
workflow to execute, the operator creates a pod using the `Pool` resource `spec.template`
property and executes the workflow on created pod, then deletes it.
When pod creation fails, the respective agent is de-registered and a new agent is created
instead. The workflow remains in `RUNNING` state and fails on timeout.
Created pod name is temporarily stored in the resource `status.create_agents.agents_pods`
property.
## License
Copyright 2024 Henix, henix.fr
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Raw data
{
"_id": null,
"home_page": "https://opentestfactory.org/guides/agent-operator.html",
"name": "opentf-agent-operator-nightly",
"maintainer": "Henix",
"docs_url": null,
"requires_python": ">=3.10.0",
"maintainer_email": "opentestfactory@henix.com",
"keywords": null,
"author": "Martin Lafaix",
"author_email": "mlafaix@henix.com",
"download_url": null,
"platform": null,
"description": "# agent-operator\n\nThis package is part of the OpenTestFactory initiative.\n\n`agent-operator` is a Kubernetes operator. It allows for declaring pools of agents\non a Kubernetes cluster and for dynamical execution environment provisioning.\n\n## Deployment\n\n`agent-operator` can be deployed on a Kubernetes cluster using a Docker image [TBC],\nor executed as a `kopf` script.\n\nWhen deploying with Docker image, you may use sample `Deployment` and RBAC\ndefinitions provided in the project `resources` directory. In the `Deployment` file,\nyou should set `ORCHESTRATOR_URL` environment variable value to\n`{orchestrator_url}:{agentchannel_port}`.\n\nWhen running as a `kopf` script (`kopf run main.py`), you should set the `ORCHESTRATOR_URL`\nand `OPERATOR_CONTEXT` environment variables values respectively to\n`{orchestrator_url}:{agentchannel_port}` and `local`.\n\n## Overview\n\n`agent-operator` monitors `Pool` resources. `CustomResourceDefinition` file and\nsample `Pool` resource file are available in the project `resources`\ndirectory. The operator supports Kubernetes namespaces, i.e. a `Pool` resource\ncan be applied in a specific namespace.\n\nThe `Pool` resource definition is as follows:\n\n```yaml\napiVersion: agent.opentestfactory.org/v1alpha1\nkind: Pool\nmetadata:\n name: {resource name} # mandatory\nspec:\n poolSize: {agents pool size} # mandatory\n tags: [list of agents tags] # mandatory\n orchestratorSecret: {Kubernetes secret name}\n namespaces: [list of orchestrator namespaces]\n template: # mandatory\n {execution pod definition}\n```\n\n`metadata.name` is the resource name.\n\n`spec.poolSize` must be a positive integer or zero. It specifies the number of agents that\nwill be registered to the orchestrator when the resource is applied on a Kubernetes cluster.\n\n`spec.tags` is a list of agent tags. All agents linked to a pool share the same tags.\n\n`spec.orchestratorSecret` is a name of a Kubernetes secret holding the orchestrator token.\n\n`spec.namespaces` is a list of orchestrator namespaces (not yet supported).\n\n`spec.template` holds a pod template serving to provide dynamical execution environments.\n\n### Pool Resource Monitoring\n\nWhen a `Pool` resource definition file is applied to a cluster, the operator\nregisters `poolSize` agents with specified `tags` on the orchestrator. Registered\nagents UUIDs are retrieved and stored as a list in the resource `status.create_agents.agents`\nproperty, which also holds `resource_id` property, identifying the created resource.\n\nThis resource is then monitored for changes. The operator listens to the `spec.poolSize`\nand `spec.tags` field updates. On pool size or tags update, if there are running\nworkflows and the update implies agents de-registration (namely changing tags or decreasing\npool size), the operator waits for their completion before applying the requested changes.\nThe resource `status.create_agents.agents` field is also updated.\n\nWhen the operator is relaunched, it retrieves registered agents list from the orchestrator,\ncleans up all busy agents and execution pods (as workflow won't be\nable to successfully complete if the connection with the operator is interrupted), then\ncompares the resulting list to the `Pool` resource agents list and registers as many new agents\nas needed.\n\nWhen a `Pool` resource is deleted, the operator waits for all running workflows to be\ncompleted before de-registering agents and allowing for resource deletion.\n\n### Workflow Execution\n\nThe operator constantly queries agents to know their status. When an agent receives a\nworkflow to execute, the operator creates a pod using the `Pool` resource `spec.template`\nproperty and executes the workflow on created pod, then deletes it.\n\nWhen pod creation fails, the respective agent is de-registered and a new agent is created\ninstead. The workflow remains in `RUNNING` state and fails on timeout.\n\nCreated pod name is temporarily stored in the resource `status.create_agents.agents_pods`\nproperty.\n\n## License\n\nCopyright 2024 Henix, henix.fr\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n",
"bugtrack_url": null,
"license": "Apache Software License (https://www.apache.org/licenses/LICENSE-2.0)",
"summary": "OpenTestFactory Orchestrator Agent Operator",
"version": "0.1.0.dev110",
"project_urls": {
"Homepage": "https://opentestfactory.org/guides/agent-operator.html"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4858f4eebb25ab70e5cb1b05939e64c3caf6b1da2b0ac91f772df10ac3c149b8",
"md5": "106d7a89e025d3a667d6d931cdabc4fa",
"sha256": "62a87ff89d9feeceb09cbc214663663cd3ee09ce9a24daecee38f5e2b7dc6d46"
},
"downloads": -1,
"filename": "opentf_agent_operator_nightly-0.1.0.dev110-py3-none-any.whl",
"has_sig": false,
"md5_digest": "106d7a89e025d3a667d6d931cdabc4fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.0",
"size": 13931,
"upload_time": "2024-11-20T10:41:39",
"upload_time_iso_8601": "2024-11-20T10:41:39.918751Z",
"url": "https://files.pythonhosted.org/packages/48/58/f4eebb25ab70e5cb1b05939e64c3caf6b1da2b0ac91f772df10ac3c149b8/opentf_agent_operator_nightly-0.1.0.dev110-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 10:41:39",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "opentf-agent-operator-nightly"
}
JSON