{"id":26878092,"url":"https://github.com/dmk/ollama-operator","last_synced_at":"2025-10-07T03:08:17.197Z","repository":{"id":284364570,"uuid":"941672058","full_name":"dmk/ollama-operator","owner":"dmk","description":"A Kubernetes operator that manages Ollama models declaratively through custom resources.","archived":false,"fork":false,"pushed_at":"2025-03-26T09:56:29.000Z","size":77,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-02T22:37:33.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-02T20:37:08.000Z","updated_at":"2025-03-26T09:56:32.000Z","dependencies_parsed_at":"2025-06-23T01:36:27.809Z","dependency_job_id":"cd777216-84af-450e-82d3-aab51b4c69fc","html_url":"https://github.com/dmk/ollama-operator","commit_stats":null,"previous_names":["dmk/ollama-operator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dmk/ollama-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmk%2Follama-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmk%2Follama-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmk%2Follama-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmk%2Follama-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmk","download_url":"https://codeload.github.com/dmk/ollama-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmk%2Follama-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278712750,"owners_count":26032749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-31T12:19:17.310Z","updated_at":"2025-10-07T03:08:17.181Z","avatar_url":"https://github.com/dmk.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ollama-operator\n\nA Kubernetes operator for declarative management of Ollama models through Kubernetes custom resources.\n\n## Description\n\nThe Ollama Operator provides a Kubernetes-native way to manage [Ollama](https://ollama.com/) models in your cluster. It allows you to:\n\n- Declaratively specify which Ollama models should be available\n- Automatically pull models when they are added as resources\n- Track the state of models (pending, pulling, ready, failed)\n- Automatically remove models when the resources are deleted\n\nThis operator makes it easy to integrate Ollama's large language models into your Kubernetes infrastructure using GitOps principles and standard Kubernetes tooling.\n\n## Getting Started\n\n### Prerequisites\n- go version v1.23.0+\n- docker version 17.03+\n- kubectl version v1.11.3+\n- Access to a Kubernetes v1.11.3+ cluster\n- [Ollama](https://ollama.com/) running in your cluster or accessible to the operator\n\n### To Deploy on the cluster\n**Build and push your image to the location specified by `IMG`:**\n\n```sh\nmake docker-build docker-push IMG=\u003csome-registry\u003e/ollama-operator:tag\n```\n\n**NOTE:** This image ought to be published in the personal registry you specified.\nAnd it is required to have access to pull the image from the working environment.\nMake sure you have the proper permission to the registry if the above commands don't work.\n\n**Install the CRDs into the cluster:**\n\n```sh\nmake install\n```\n\n**Deploy the Manager to the cluster with the image specified by `IMG`:**\n\n```sh\nmake deploy IMG=\u003csome-registry\u003e/ollama-operator:tag\n```\n\n\u003e **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin\nprivileges or be logged in as admin.\n\n### Create Ollama Model Resources\n\nOnce the operator is running, you can create OllamaModel custom resources to manage models. For example:\n\n```yaml\napiVersion: ollama.smithforge.dev/v1alpha1\nkind: OllamaModel\nmetadata:\n  name: llama3.2-1b\nspec:\n  name: llama3.2  # Model name (as recognized by Ollama)\n  tag: 1b         # Model tag/version\n```\n\nThe operator will ensure that the specified model is pulled and ready in your Ollama instance. You can check the status using:\n\n```sh\nkubectl get ollamamodels\n```\n\nSample resources can be found in the `config/samples/` directory.\n\nYou can apply the samples with:\n\n```sh\nkubectl apply -k config/samples/\n```\n\n### Current Status and Limitations\n\nThe operator has been tested with a standard Kubernetes setup. Note that:\n\n- The operator does not deploy Ollama itself - it manages models for an existing Ollama installation\n- GPU acceleration requires proper configuration of your Ollama deployment\n- For production use cases, you may need to customize resource limits\n\n## Technical Details\n\n### Custom Resource Definition\n\nThe operator introduces a new Custom Resource Definition (CRD) called `OllamaModel` with the following specification:\n\n```yaml\nspec:\n  name: \u003cmodel-name\u003e   # Name of the Ollama model (e.g., llama3.2, gemma3)\n  tag: \u003cmodel-tag\u003e     # Version/tag of the model (e.g., 7b, 1b)\n```\n\nThe resource reports the following status fields:\n\n```yaml\nstatus:\n  state: \u003cpending|pulling|ready|failed\u003e  # Current state of the model\n  lastPullTime: \u003ctimestamp\u003e              # When the model was last pulled\n  digest: \u003csha256\u003e                       # Model file SHA256 digest\n  size: \u003cbytes\u003e                          # Size of the model in bytes\n  error: \u003cmessage\u003e                       # Error message if in failed state\n```\n\n### Architecture\n\nThe operator connects to the Ollama API to:\n1. Check if requested models exist\n2. Pull models that don't exist\n3. Delete models when resources are removed\n4. Update status information about each model\n\n## Advanced Features\n\n### Model Refresh/Update\n\nYou can force a model to be refreshed or updated using annotations:\n\n```yaml\napiVersion: ollama.smithforge.dev/v1alpha1\nkind: OllamaModel\nmetadata:\n  name: llama3.2-1b\n  annotations:\n    ollama.smithforge.dev/refresh: \"true\"  # Triggers a model refresh\nspec:\n  name: llama3.2\n  tag: 1b\n```\n\nThis is useful when Ollama releases updates to existing models or when you need to force a re-pull of a model.\n\nTo trigger a refresh using kubectl:\n\n```sh\nkubectl annotate ollamamodel llama3.2-1b ollama.smithforge.dev/refresh=true --overwrite\n```\n\nAfter processing the refresh, the annotation value will be updated with a timestamp to indicate completion.\n\n## Roadmap\n\nThe following features are planned for upcoming releases:\n\n1. **Model Updates/Refreshes** - Force models to be re-pulled using annotations (implemented)\n2. **HTTP API** - RESTful API for managing models without direct Kubernetes access (implemented)\n3. **Error Recovery** - Automatically recover if Ollama loses models but the CRD still exists\n4. **Health Checks** - Periodically verify models are still available in Ollama\n5. **Resource Management** - Add configuration for resource limits/requests\n6. **Events** - Record Kubernetes events for important state changes\n7. **Metrics** - Export Prometheus metrics for model usage and metadata\n8. **Webhook Validation** - Add validation webhooks to prevent invalid configurations\n9. **Multiple Ollama Instances** - Support targeting different Ollama instances\n\n## HTTP API\n\nThe operator provides an optional HTTP API server that allows you to manage Ollama models without direct access to the Kubernetes API. This is particularly useful for integrating with applications that don't have Kubernetes credentials.\n\n### Enabling the API Server\n\nTo enable the API server, pass the `--enable-api-server` flag when running the operator:\n\n```sh\n# When running locally\nmake run ARGS=\"--enable-api-server --api-server-bind-address=:8082\"\n\n# When deploying to Kubernetes\n# Edit config/manager/kustomization.yaml to add the following flags:\n# --enable-api-server --api-server-bind-address=:8082\n```\n\n### API Authentication\n\nYou can secure the API with an API key by using the `--api-server-key` flag:\n\n```sh\nmake run ARGS=\"--enable-api-server --api-server-bind-address=:8082 --api-server-key=your-secret-key\"\n```\n\nClients must then include this key in the `X-API-Key` header when making requests.\n\n### API Endpoints\n\nThe API provides the following endpoints:\n\n- `GET /api/v1/models` - List all models\n- `GET /api/v1/models/{name}` - Get details of a specific model\n- `POST /api/v1/models` - Create a new model\n- `DELETE /api/v1/models/{name}` - Delete a model\n- `POST /api/v1/models/{name}/refresh` - Refresh a model\n\nSee the [API docs](docs/api-usage.md) for detailed usage instructions and client code samples.\n\n## Uninstalling\n\n**Delete all model instances (CRs) from the cluster:**\n\n```sh\nkubectl delete -k config/samples/\n```\n\n**Delete the APIs (CRDs) from the cluster:**\n\n```sh\nmake uninstall\n```\n\n**Undeploy the controller from the cluster:**\n\n```sh\nmake undeploy\n```\n\n## License\n\nCopyright 2025.\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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmk%2Follama-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmk%2Follama-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmk%2Follama-operator/lists"}