{"id":13451633,"url":"https://github.com/deislabs/osiris","last_synced_at":"2025-03-23T19:32:14.194Z","repository":{"id":48190069,"uuid":"159882001","full_name":"deislabs/osiris","owner":"deislabs","description":"A general purpose, scale-to-zero component for Kubernetes","archived":true,"fork":false,"pushed_at":"2020-03-19T15:28:23.000Z","size":4642,"stargazers_count":462,"open_issues_count":27,"forks_count":51,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-04T13:46:09.680Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deislabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2018-11-30T21:45:24.000Z","updated_at":"2024-12-11T15:47:57.000Z","dependencies_parsed_at":"2022-09-12T10:41:29.535Z","dependency_job_id":null,"html_url":"https://github.com/deislabs/osiris","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deislabs%2Fosiris","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deislabs%2Fosiris/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deislabs%2Fosiris/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deislabs%2Fosiris/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deislabs","download_url":"https://codeload.github.com/deislabs/osiris/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245157976,"owners_count":20570105,"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","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":"2024-07-31T07:00:57.468Z","updated_at":"2025-03-23T19:32:12.768Z","avatar_url":"https://github.com/deislabs.png","language":"Go","funding_links":[],"categories":["Go","Operators vs Controllers","Serverless Platforms"],"sub_categories":["Autoscaling / Scheduling"],"readme":"# Osiris - A general purpose, Scale to Zero component for Kubernetes\n\n[![CircleCI](https://circleci.com/gh/deislabs/osiris/tree/master.svg?style=svg)](https://circleci.com/gh/deislabs/osiris/tree/master)\n\nOsiris enables greater resource efficiency within a Kubernetes cluster by\nallowing idling workloads to automatically scale-to-zero and allowing\nscaled-to-zero workloads to be automatically re-activated on-demand by inbound\nrequests.\n\n__Osiris, as a concept, is highly experimental and currently remains under heavy\ndevelopment.__\n\n## How it works\n\nVarious types of Kubernetes resources can be Osiris-enabled using an annotation.\n\nOsiris-enabled pods are automatically instrumented with a __metrics-collecting\nproxy__ deployed as a sidecar container.\n\nOsiris-enabled deployments (if _already_ scaled to a configurable minimum number\nof replicas-- one by default) automatically have metrics from their pods\ncontinuously scraped and analyzed by the __zeroscaler__ component. When the\naggregated metrics reveal that all of the deployment's pods are idling, the\nzeroscaler scales the deployment to zero replicas.\n\nUnder normal circumstances, scaling a deployment to zero replicas poses a\nproblem: any services that select pods from that deployment (and only that\ndeployment) would lose _all_ of their endpoints and become permanently\nunavailable. Osiris-enabled services, however, have their endpoints managed by\nthe Osiris __endpoints controller__ (instead of Kubernetes' built-in endpoints\ncontroller). The Osiris endpoints controller will automatically add Osiris\n__activator__ endpoints to any Osiris-enabled service that has lost the rest of\nits endpoints.\n\nThe Osiris __activator__ component receives traffic for Osiris-enabled services\nthat are lacking any application endpoints. The activator initiates a scale-up\nof a corresponding deployment to a configurable minimum number of replicas (one,\nby default). When at least one application pod becomes ready, the request will\nbe forwarded to the pod.\n\nAfter the activator \"reactivates\" the deployment, the __endpoints controller__\n(described above) will naturally observe the availability of application\nendpoints for any Osiris-enabled services that select those pods and will\nremove activator endpoints from that service. All subsequent traffic for the\nservice will, once again, flow directly to application pods... until a period of\ninactivity causes the zeroscaler to take the application offline again.\n\n### Scaling to zero and the HPA\n\nOsiris is designed to work alongside the [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) and\nis not meant to replace it-- it will scale your pods from n to 0 and from 0 to\nn, where n is a configurable minimum number of replicas (one, by default). All\n_other_ scaling decisions may be delegated to an HPA, if desired.\n\nThis diagram better illustrates the different roles of Osiris, the HPA and the\nCluster Autoscaler:\n\n![diagram](diagram.svg)\n\n## Setup\n\nPrerequisites:\n\n* [Helm](https://docs.helm.sh/using_helm/#installing-helm) (v3.0.0 or greater)\n* A running Kubernetes cluster.\n\n### Installation\n\nOsiris' Helm chart is hosted in an\n[Azure Container Registry](https://azure.microsoft.com/en-us/services/container-registry/),\nwhich does not yet support anonymous access to charts therein. Until this is\nresolved, adding the Helm repository from which Osiris can be installed requires\nuse of a shared set of read-only credentials.\n\nMake sure helm is initialized in your running kubernetes cluster.\n\nFor more details on initializing helm, Go [here](https://docs.helm.sh/helm/#helm)\n\n```\nhelm repo add osiris https://osiris.azurecr.io/helm/v1/repo \\\n  --username eae9749a-fccf-4a24-ac0d-6506fe2a6ab3 \\\n  --password =s-e.2-84BhIo6LM6=/l4C_sFzxb=sT[\n```\n\nInstallation requires use of the `--devel` flag to indicate pre-release versions\nof the specified chart are eligible for download and installation. The following\ncommand install the latest version of Osiris with the default values for all\noptions - see the next section for all available installation options.\n\n```\nkubectl create namespace osiris-system\nhelm install osiris osiris/osiris-edge \\\n  --namespace osiris-system \\\n  --devel\n```\n\n#### Installation Options\n\nOsiris global configuration is minimal - because most of it will be done by the users\nwith annotations on the Kubernetes resources.\n\nThe following table lists the configurable parameters of the Helm chart and their default values.\n\n| Parameter | Description | Default |\n| --------- | ----------- | ------- |\n| `zeroscaler.metricsCheckInterval` | The interval in which the zeroScaler would repeatedly track the pod http request metrics. The value is the number of seconds of the interval. Note that this can also be set on a per-deployment basis, with an annotation. | `150` |\n\nExample of installation with Helm and a custom configuration:\n\n```\nkubectl create namespace osiris-system\nhelm install osiris osiris/osiris-edge \\\n  --namespace osiris-system \\\n  --devel \\\n  --set zeroscaler.metricsCheckInterval=600\n```\n\n## Usage\n\nOsiris will not affect the normal behavior of any Kubernetes resource without\nexplicitly being directed to do so.\n\nTo enabled the zeroscaler to scale a deployment with idling pods to zero\nreplicas, annotate the deployment like so:\n\n```\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  namespace: my-aoo\n  name: my-app\n  annotations:\n    osiris.deislabs.io/enabled: \"true\"\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: my-app\n  template:\n    metadata:\n      labels:\n        app: nginx\n      annotations:\n        osiris.deislabs.io/enabled: \"true\"\n    # ...\n  # ...\n```\n\nNote that the template for the pod _also_ uses an annotation to enable Osiris--\nin this case, it enables the metrics-collecting proxy sidecar container on all\nof the deployment's pods.\n\nIn Kubernetes, there is no direct relationship between deployments and services.\nDeployments manage pods and services may select pods managed by one or more\ndeployments. Rather than attempt to infer relationships between deployments and\nservices and potentially impact service behavior without explicit consent,\nOsiris requires services to explicitly opt-in to management by the Osiris\nendpoints controller. Such services must also utilize an annotation to indicate\nwhich deployment should be reactivated when the activator component intercepts a\nrequest on their behalf. For example:\n\n```\nkind: Service\napiVersion: v1\nmetadata:\n  namespace: my-namespace\n  name: my-app\n  annotations:\n    osiris.deislabs.io/enabled: \"true\"\n    osiris.deislabs.io/deployment: my-app\nspec:\n  selector:\n    app: my-app\n  # ...\n```\n\n### Configuration\n\nMost of Osiris configuration is done with Kubernetes annotations - as seen in the Usage section.\n\n#### Deployment Annotations\n\nThe following table lists the supported annotations for Kubernetes `Deployments` and their default values.\n\n| Annotation | Description | Default |\n| ---------- | ----------- | ------- |\n| `osiris.deislabs.io/enabled` | Enable the zeroscaler component to scrape and analyze metrics from the deployment's pods and scale the deployment to zero when idle. Allowed values: `y`, `yes`, `true`, `on`, `1`. | _no value_ (= disabled) |\n| `osiris.deislabs.io/minReplicas` | The minimum number of replicas to set on the deployment when Osiris will scale up. If you set `2`, Osiris will scale the deployment from `0` to `2` replicas directly. Osiris won't collect metrics from deployments which have more than `minReplicas` replicas - to avoid useless collections of metrics. | `1` |\n| `osiris.deislabs.io/metricsCheckInterval` | The interval in which Osiris would repeatedly track the pod http request metrics. The value is the number of seconds of the interval. Note that this value override the global value defined by the `zeroscaler.metricsCheckInterval` Helm value. | _value of the `zeroscaler.metricsCheckInterval` Helm value_ |\n\n#### Pod Annotations\n\nThe following table lists the supported annotations for Kubernetes `Pods` and their default values.\n\n| Annotation | Description | Default |\n| ---------- | ----------- | ------- |\n| `osiris.deislabs.io/enabled` | Enable the metrics collecting proxy sidecar container to be injected into this pod. Allowed values: `y`, `yes`, `true`, `on`, `1`. | _no value_ (= disabled) |\n| `osiris.deislabs.io/ignoredPaths` | The list of (url) paths that should be \"ignored\" by Osiris. Requests to such paths won't be \"counted\" by the proxy. Format: comma-separated string. | _no value_ |\n\n#### Service Annotations\n\nThe following table lists the supported annotations for Kubernetes `Services` and their default values.\n\n| Annotation | Description | Default |\n| ---------- | ----------- | ------- |\n| `osiris.deislabs.io/enabled` | Enable this service's endpoints to be managed by the Osiris endpoints controller. Allowed values: `y`, `yes`, `true`, `on`, `1`. | _no value_ (= disabled) |\n| `osiris.deislabs.io/deployment` | Name of the deployment which is behind this service. This is _required_ to map the service with its deployment. | _no value_ |\n| `osiris.deislabs.io/loadBalancerHostname` | Map requests coming from a specific hostname to this service. Note that if you have multiple hostnames, you can set them with different annotations, using `osiris.deislabs.io/loadBalancerHostname-1`, `osiris.deislabs.io/loadBalancerHostname-2`, ... | _no value_ |\n| `osiris.deislabs.io/ingressHostname` | Map requests coming from a specific hostname to this service. If you use an ingress in front of your service, this is required to create a link between the ingress and the service. Note that if you have multiple hostnames, you can set them with different annotations, using `osiris.deislabs.io/ingressHostname-1`, `osiris.deislabs.io/ingressHostname-2`, ... | _no value_ |\n| `osiris.deislabs.io/ingressDefaultPort` | Custom service port when the request comes from an ingress. Default behaviour if there are more than 1 port on the service, is to look for a port named `http`, and fallback to the port `80`. Set this if you have multiple ports and using a non-standard port with a non-standard name. | _no value_ |\n| `osiris.deislabs.io/tlsPort` | Custom port for TLS-secured requests. Default behaviour if there are more than 1 port on the service, is to look for a port named `https`, and fallback to the port `443`. Set this if you have multiple ports and using a non-standard TLS port with a non-standard name. | _no value_ |\n\nNote that you might see an `osiris.deislabs.io/selector` annotation - this is for internal use only, and you shouldn't try to set/update or delete it.\n\n### Demo\n\nDeploy the [example application](example/hello-osiris.yaml) `hello-osiris` :\n\n```\nkubectl create -f ./example/hello-osiris.yaml\n```\n\nThis will create an Osiris-enabled deployment and service named `hello-osiris`.\n\nGet the External IP of the `hello-osiris` service once it appears:\n\n```\nkubectl get service hello-osiris -o jsonpath='{.status.loadBalancer.ingress[*].ip}'\n```\n\nPoint your browser to `\"http://\u003cEXTERNAL-IP\u003e\"`, and verify that\n`hello-osiris` is serving traffic.\n\nAfter about 2.5 minutes, the Osiris-enabled deployment should scale to zero\nreplicas and the one `hello-osiris` pod should be terminated.\n\nMake a request again, and watch as Osiris scales the deployment back to one\nreplica and your request is handled successfully.\n\n## Limitations\n\nIt is a specific goal of Osiris to enable greater resource efficiency within\nKubernetes clusters, in general, but especially with respect to \"nodeless\"\nKubernetes options such as\n[Virtual Kubelet](https://github.com/virtual-kubelet/virtual-kubelet) or\n[Azure Kubernetes Service Virtual Nodes](https://docs.microsoft.com/en-us/azure/aks/virtual-nodes-portal), however,\ndue to known issues with those technologies, Osiris remains incompatible with\nthem for the near term.\n\n## Contributing\n\nOsiris follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeislabs%2Fosiris","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeislabs%2Fosiris","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeislabs%2Fosiris/lists"}