{"id":13463783,"url":"https://github.com/libopenstorage/stork","last_synced_at":"2025-05-14T16:02:35.509Z","repository":{"id":38362032,"uuid":"102562155","full_name":"libopenstorage/stork","owner":"libopenstorage","description":"Stork - Storage Orchestration Runtime for Kubernetes","archived":false,"fork":false,"pushed_at":"2025-02-12T08:30:36.000Z","size":178216,"stargazers_count":398,"open_issues_count":86,"forks_count":88,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-12T20:43:52.458Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libopenstorage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2017-09-06T04:20:51.000Z","updated_at":"2025-03-26T16:14:03.000Z","dependencies_parsed_at":"2023-12-21T00:56:43.089Z","dependency_job_id":"583c8bac-d634-4b97-9b66-5ccc6deade15","html_url":"https://github.com/libopenstorage/stork","commit_stats":null,"previous_names":[],"tags_count":114,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libopenstorage%2Fstork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libopenstorage%2Fstork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libopenstorage%2Fstork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libopenstorage%2Fstork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libopenstorage","download_url":"https://codeload.github.com/libopenstorage/stork/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254179903,"owners_count":22027884,"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-31T14:00:28.476Z","updated_at":"2025-05-14T16:02:30.496Z","avatar_url":"https://github.com/libopenstorage.png","language":"Go","funding_links":[],"categories":["Storage","Tools","Roadmap","Go","Repository is obsolete","HarmonyOS","Featured On"],"sub_categories":["[Tutorials](#tutorials)","Awesome Operators in the Wild","Windows Manager"],"readme":"[![Build Status](https://travis-ci.org/libopenstorage/stork.svg?branch=master)](https://travis-ci.org/libopenstorage/stork)\n[![Go Report Card](https://goreportcard.com/badge/github.com/libopenstorage/stork)](https://goreportcard.com/report/libopenstorage/stork)\n[![Docker Pulls](https://img.shields.io/docker/pulls/openstorage/stork.svg)](https://hub.docker.com/r/openstorage/stork)\n[![Code Coverage](https://codecov.io/gh/libopenstorage/stork/branch/master/graph/badge.svg)](https://codecov.io/gh/libopenstorage/stork)\n\n# Stork - Storage Operator Runtime for Kubernetes\nStork is a Cloud Native storage operator runtime scheduler plugin. It translates a scheduler's orchestration decisions into someting that an external cloud native storage solution can act upon. By doing so, it extends Kubernetes with more stateful awareness of the underlying storage provider, its capabilities and state.\n\n\u003cdiv style=\"text-align:center\"\u003e\u003cimg src=\"images/stork.png\" alt=\"Drawing\" style=\"width: 50px;\"/\u003e\u003c/div\u003e\n\nStork is intended to allow storage operators such as Portworx, EMC-RexRay, and Kubernetes Local Storage to extend upon scheduler actions and allow for a storage-implementation specific orchestration actions around what the orchestrator is trying to do. The most basic example is when the scheduler is trying to spawn a container that is part of a pod - Stork will allow for the storage provider to specify an appropriate node on which that container needs to run such that it's data access is local to the runtime of the container. This is one of many orchestration scenarios that is adressed by this project.\n\n# Features\n## Hyper-Convergence\nStork can be used to co-locate pods with where their data is located. This is achieved by using a\n[kubernetes scheduler extender](https://github.com/kubernetes/kubernetes/issues/11470).\nThe scheduler is configured to use stork as an extender. So every time a pod is being scheduled,\nthe scheduler will send filter and prioritize requests to stork. Stork will then\ncheck with the storage driver\nYou can either configure the default kubernetes scheduler to communicate with\nstork or launch another instance of kube-scheduler.\n\n### Initializer (Experimental)\nIf you are not able to update the schedulerName for you applications to use\nstork, you can enable the app-initializer feature. This uses the Kubernetes\n[AdmissionController Initializer](https://kubernetes.io/docs/admin/extensible-admission-controllers/#initializers)\nfeature to automatically update the scheduler to stork if your application\n(deployment or statefulset) is using volumes backed by the configured driver.\n\nTo enable the Initializer you need to:\n* [Enable the Intializer feature in your Kubernetes cluster](https://kubernetes.io/docs/admin/extensible-admission-controllers/#enable-initializers-alpha-feature)\nsince it is an alpha feature.\n* Add \"--app-initializer=true\" option to stork (in either the deployment or daemonset spec file)\n* Add the [stork-initializer spec](specs/stork-initializer.yaml) to you Kubernetes cluster using `kubectl create -f stork-initializer.yaml`\n\n## Health Monitoring\nStork will monitor the health of the volume driver on the different nodes. If the volume driver on a node becomes\nunhealthy pods on that node using volumes from the driver will not be able to access their data. In this case stork will\nrelocate  pods on to other nodes so that they can continue running.\n\n## Volume Snapshots\n\nStork uses the external-storage project from [kubernetes-incubator](https://github.com/kubernetes-incubator/external-storage)\nto add support for snapshots.\n\nRefer to [Snapshots with Stork](doc/snaps.md) for instructions on creating and using snapshots with Stork.\n\n### Application consistent Snapshots\n\nThis feature allows you to specify pre and post rules that are run on the application pods before and after a snapshot is triggered. This allows users to perform actions like quiescing or flushing data from applications before a snapshot is taken and resume I/O after the snapshot is taken. The commands will be run in pods which are using the PVC being snapshotted.\n\nRead [Configuring application consistent snapshots](/doc/snaps-3d.md) for further details.\n\n\n# Building Stork\nStork is written in Golang. To build Stork:\n\n```\n# git clone git@github.com:libopenstorage/stork.git\n# export DOCKER_HUB_REPO=myrepo\n# export DOCKER_HUB_STORK_IMAGE=stork\n# export DOCKER_HUB_STORK_TAG=latest\n# export DOCKER_HUB_CMD_EXECUTOR_IMAGE=cmdexecutor\n# export DOCKER_HUB_CMD_EXECUTOR_TAG=latest\n# make\n# make container\n# make deploy\n```\n\nThis will create the Docker image `$(DOCKER_HUB_REPO)/$(DOCKER_HUB_STORK_IMAGE):$(DOCKER_HUB_TAG)`.\n\n# Running Stork\nNow that you have stork in a container image, you can just create a pod config for it and run it in your Kubernetes cluster. We do this via a deployment.\n\n## Create a Deployment\nA Deployment manages a Replica Set which in turn manages the pods, thereby making stork resilient to failures. The deployment spec is defined in [specs/stork-deployment.yaml](https://raw.githubusercontent.com/libopenstorage/stork/master/specs/stork-deployment.yaml).\nBy default the deployment does the following\n* Uses the latest stable image of stork to start a pod. You can update the tag to use a specific version or use your own stork image.\n* Creates a service to provide an endpoint that can be used to reach the extender. \n* Creates a ConfigMap which can be used by a scheduler to communicate with stork.\n* Uses the Portworx (pxd) driver for stork.\n\n## Run Stork in your Kubernetes cluster\nYou can either update the default kube scheduler to use stork or start a new\nscheduler instance which can use stork. \nOnce this has been deployed the scheduler can be used to schedule any pods with the added advantage that it will\nalso try to optimize the storage requirements for the pod.\n\n### Start a new scheduler instance and configure it with Stork (recommended)\nYou might not always have access to your default scheduler to update it's config options.\nSo the recommended way to start stork is to launch another instance of the scheduler and configure it to use stork\n\nIn order to run stork in your Kubernetes cluster, just create the deployment specified in the config above in a Kubernetes cluster:\n\n```\n# kubectl create -f stork-deployment.yaml\n```\n\nVerify that the stork pod is running:\n\n```\n# kubectl get pods --namespace=kube-system\nNAME                              READY     STATUS    RESTARTS   AGE\n....\nstork-6dc5d66997-4rs2w            1/1       Running   1          27m\nstork-6dc5d66997-fl8wr            1/1       Running   1          27m\nstork-6dc5d66997-xvnbj            1/1       Running   1          27m\n....\n```\n\nWe will then start a new scheduler instance here and configure it to use stork. We will call the new scheduler 'stork'.\nThis new scheduler instance is defined in [specs/stork-scheduler.yaml](https://raw.githubusercontent.com/libopenstorage/stork/master/specs/stork-scheduler.yaml).\nThis spec starts 3 replicas of the scheduler.\n\nYou will need to update the version of kube scheduler that you want to use. This should be the same version as your kubernetes cluster. \nExample for Kubernetes v1.8.1 it would be:\n```\nimage: gcr.io/google_containers/kube-scheduler-amd64:v1.8.1\n```\n\nYou can deploy it by running the following command:\n```\n# kubectl create -f stork-scheduler.yaml\n```\nVerify that the scheduler pods are running:\n\n```\n# kubectl get pods --namespace=kube-system\nNAME                              READY     STATUS    RESTARTS   AGE\n....\nstork-scheduler-9d6cb4546-gqdq2   1/1       Running   0          32m\nstork-scheduler-9d6cb4546-k4z8t   1/1       Running   0          32m\nstork-scheduler-9d6cb4546-tfkh4   1/1       Running   0          30m\n....\n```\n\n### Configure your default scheduler with Stork\nWhen using stork with the default scheduler, stork needs to be run as a deamon set. This is to avoid a deadlock\nwhen trying to schedule the stork pods from the scheduler.\n\nFirst create the stork daemonset defined in [specs/stork-daemonset.yaml](https://raw.githubusercontent.com/libopenstorage/stork/master/specs/stork-daemonset.yaml)\n\n```\n# kubectl create -f stork-daemonset.yaml\n```\n\nVerify that the stork pod is running:\n\n```\n# kubectl get pods --namespace=kube-system\nNAME                              READY     STATUS    RESTARTS   AGE\n....\nstork-6dc5d66997-4rs2w            1/1       Running   1          27m\nstork-6dc5d66997-fl8wr            1/1       Running   1          27m\nstork-6dc5d66997-xvnbj            1/1       Running   1          27m\n....\n```\n\nTo configure your default scheduler to use stork add the following arguments to the scheduler and restart the scheduler if required:\n```\n--policy-configmap=stork-config --policy-configmap-namespace=kube-system\n```\n\nYou will also need to make sure that the kube-scheduler clusterrole has permissions to read config maps. If not, run the following command:\n```\n# kubectl edit clusterrole -n kube-system system:kube-scheduler\n```\n\nAnd add the following permissions:\n```\n- apiGroups: ['']\n  resources: ['configmaps']\n  verbs: ['get']\n```\n\n## Specify the Stork scheduler for pods\nIn order to schedule a given pod using the Stork scheduler, specify the name of the scheduler in that pod spec:\n\n```yaml\nkind: PersistentVolumeClaim\napiVersion: v1\nmetadata:\n   name: mysql-data\n   annotations:\n     volume.beta.kubernetes.io/storage-class: px-mysql-sc\nspec:\n   accessModes:\n     - ReadWriteOnce\n   resources:\n     requests:\n       storage: 2Gi\n---\nkind: StorageClass\napiVersion: storage.k8s.io/v1\nmetadata:\n    name: px-mysql-sc\nprovisioner: kubernetes.io/portworx-volume\nparameters:\n   repl: \"2\"\n---\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: mysql\nspec:\n  strategy:\n    rollingUpdate:\n      maxSurge: 1\n      maxUnavailable: 1\n    type: RollingUpdate\n  replicas: 1\n  selector:\n    matchLabels:\n      app: mysql\n  template:\n    metadata:\n      labels:\n        app: mysql\n        version: \"1\"\n    spec:\n      schedulerName: stork\n      containers:\n      - image: mysql:5.6\n        name: mysql\n        env:\n        - name: MYSQL_ROOT_PASSWORD\n          value: password\n        ports:\n        - containerPort: 3306\n        volumeMounts:\n        - name: mysql-persistent-storage\n          mountPath: /var/lib/mysql\n      volumes:\n      - name: mysql-persistent-storage\n        persistentVolumeClaim:\n          claimName: mysql-data\n```\n\nThe above spec will create a mysql pod with a Portworx volume having 2 replicas.\nThe pod will then get scheduled on a node in the cluster where one of the replicas is located.\nIf one of those nodes does not have enough cpu or memory resources then it will get scheduled on any other node in the cluster\nwhere the driver (in this case Portworx) is running.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibopenstorage%2Fstork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibopenstorage%2Fstork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibopenstorage%2Fstork/lists"}