{"id":37139862,"url":"https://github.com/stackitcloud/yawol","last_synced_at":"2026-01-14T16:18:31.857Z","repository":{"id":61627991,"uuid":"526524108","full_name":"stackitcloud/yawol","owner":"stackitcloud","description":"yawol is a Load Balancer solution for OpenStack, based on the Kubernetes controller pattern.","archived":false,"fork":false,"pushed_at":"2025-12-21T04:45:16.000Z","size":1274,"stargazers_count":52,"open_issues_count":17,"forks_count":6,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-12-22T20:45:24.563Z","etag":null,"topics":["kubebuilder","kubernetes","load-balancer","loadbalancer","openstack","ske"],"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/stackitcloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-19T08:27:52.000Z","updated_at":"2025-10-05T09:21:59.000Z","dependencies_parsed_at":"2023-02-17T19:46:03.523Z","dependency_job_id":null,"html_url":"https://github.com/stackitcloud/yawol","commit_stats":null,"previous_names":[],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/stackitcloud/yawol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fyawol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fyawol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fyawol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fyawol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackitcloud","download_url":"https://codeload.github.com/stackitcloud/yawol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fyawol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28425635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T15:24:48.085Z","status":"ssl_error","status_checked_at":"2026-01-14T15:23:41.940Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["kubebuilder","kubernetes","load-balancer","loadbalancer","openstack","ske"],"created_at":"2026-01-14T16:18:31.055Z","updated_at":"2026-01-14T16:18:31.851Z","avatar_url":"https://github.com/stackitcloud.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo.svg\" alt=\"yawol\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cem\u003eDo OpenStack Load Balancing the Kubernetes Way.\u003c/em\u003e\n\u003c/p\u003e\n\n****\n\nyawol (**y**et **a**nother **w**orking **O**penStack **L**oad Balancer) is a\nLoad Balancer solution for OpenStack, based on the Kubernetes controller\npattern.\n\n****\n\n## Key Features\n\n* Replacement for OpenStack Octavia Load Balancing\n* Provides Load Balancers for Kubernetes `Services`\n* Fully manages the instance lifecycle of Load Balancer VMs\n* Kubernetes-native approach: All the benefits of CRDs and controllers\n\n## How It Works\n\nyawol uses [kubebuilder](https://kubebuilder.io/) as the controller\nframework and [gophercloud](https://github.com/gophercloud/gophercloud) for the\nOpenStack integration. The actual load balancing is done by\n[Envoy](https://www.envoyproxy.io/).\n\nFor a more in-detail description, see [the components documentation](docs/components.md).\n\n## Installation\n\n\u003e If this installation guide doesn't work for you, or if some instructions are\n\u003e unclear, please open an issue!\n\nWe provide a Helm chart for yawol in [charts/yawol-controller](charts/yawol-controller/)\nthat you can use for a quick installation on a Kubernetes cluster. In order to\nget yawol going, however, you need a yawol OpenStack VM image first.\n\n### yawol OpenStack Image\n\n#### Create alpine base image\n\nWe use an openstack alpine base image which can be created with this\n[packer file](https://github.com/stackitcloud/alpine-openstack-image).\n\n#### Preparation of packer environment\n\nTo create the necessary environment to build the image, you can use the terraform code located within `hack/packer-infrastructure`.\n\nYou can run this terraform code with the `Earthly` step `+build-packer-environment`. To be able to log in to OpenStack make sure you source your OpenStack Credentials. The following OpenStack ENV variables are needed to build the image: `OS_AUTH_URL` `OS_PROJECT_ID` `OS_PROJECT_NAME` `OS_USER_DOMAIN_NAME` `OS_PASSWORD` `OS_USERNAME` `OS_REGION_NAME`\n\nTo connect the OpenStack network with the internet, a floating IP is needed. You can specify the floating IP network with the `Earthly` argument `FLOATING_NETWORK_NAME` (default is `floating-net`).\n\n```shell\nearthly +build-packer-environment \\\n   --OS_AUTH_URL=\"$OS_AUTH_URL\" \\\n   --OS_PROJECT_ID=\"$OS_PROJECT_ID\" \\\n   --OS_PROJECT_NAME=\"$OS_PROJECT_NAME\" \\\n   --OS_USER_DOMAIN_NAME=\"$OS_USER_DOMAIN_NAME\" \\\n   --OS_PASSWORD=\"$OS_PASSWORD\" \\\n   --OS_USERNAME=\"$OS_USERNAME\" \\\n   --OS_REGION_NAME=\"$OS_REGION_NAME\"\n#  --OS_CACERT=\"$OS_CACERT\" # optional, should be the full CA bundle, not a file path\n#  --FLOATING_NETWORK_NAME=floating-net\n```\n\n\u003e Note that the terraform state is locally in the `hack/packer-infrastructure` folder.\n\nTo clean up the resources the `Earthly` step `+destroy-packer-environment` can be used.\n\n```shell\nearthly +destroy-packer-environment \\\n   --OS_AUTH_URL=\"$OS_AUTH_URL\" \\\n   --OS_PROJECT_ID=\"$OS_PROJECT_ID\" \\\n   --OS_PROJECT_NAME=\"$OS_PROJECT_NAME\" \\\n   --OS_USER_DOMAIN_NAME=\"$OS_USER_DOMAIN_NAME\" \\\n   --OS_PASSWORD=\"$OS_PASSWORD\" \\\n   --OS_USERNAME=\"$OS_USERNAME\" \\\n   --OS_REGION_NAME=\"$OS_REGION_NAME\"\n#  --OS_CACERT=\"$OS_CACERT\" # optional, should be the full CA bundle, not a file path\n#  --FLOATING_NETWORK_NAME=floating-net\n```\n\n#### Build yawol OpenStack Image\n\nBefore running our `Earthly` targets, set the needed environment variables:\n\n```shell\n# set OS_NETWORK_ID, OS_FLOATING_NETWORK_ID, OS_SECURITY_GROUP_ID from terraform state\nsource \u003c(jq -r '.outputs | del(.OS_SOURCE_IMAGE) | keys[] as $k | \"export \\($k)=\\(.[$k].value)\"' hack/packer-infrastructure/terraform.tfstate)\nexport OS_SOURCE_IMAGE=\u003cfrom your openstack environment\u003e\nexport IMAGE_VISIBILITY=\u003cprivate or public\u003e \n```\n\nLike in the step above, to be able to log in to OpenStack make sure you source your OpenStack Credentials. To specify the machine flavor and volume type the `Earthly` arguments `MACHINE_FLAVOR` and `VOLUME_TYPE` can be used (default is `MACHINE_FLAVOR=c2i.2` and `VOLUME_TYPE=storage_premium_perf6`).\n\nThen validate and build the image:\n\n```shell\nearthly +validate-yawollet-image\n```\n\n```shell\nearthly --platform=linux/amd64 +build-yawollet-image \\\n   --OS_NETWORK_ID=\"$OS_NETWORK_ID\" \\\n   --OS_FLOATING_NETWORK_ID=\"$OS_FLOATING_NETWORK_ID\" \\\n   --OS_SECURITY_GROUP_ID=\"$OS_SECURITY_GROUP_ID\" \\\n   --OS_SOURCE_IMAGE=\"$OS_SOURCE_IMAGE\" \\\n   --IMAGE_VISIBILITY=\"$IMAGE_VISIBILITY\" \\\n   --OS_AUTH_URL=\"$OS_AUTH_URL\" \\\n   --OS_PROJECT_ID=\"$OS_PROJECT_ID\" \\\n   --OS_PROJECT_NAME=\"$OS_PROJECT_NAME\" \\\n   --OS_USER_DOMAIN_NAME=\"$OS_USER_DOMAIN_NAME\" \\\n   --OS_PASSWORD=\"$OS_PASSWORD\" \\\n   --OS_USERNAME=\"$OS_USERNAME\" \\\n   --OS_REGION_NAME=\"$OS_REGION_NAME\"\n#  --OS_CACERT=\"$OS_CACERT\" # optional, should be the full CA bundle, not a file path\n#  --MACHINE_FLAVOR=c2i.2\n#  --VOLUME_TYPE=storage_premium_perf6\n```\n\n### Cluster Installation\n\nThe in-cluster components of yawol (`yawol-cloud-controller` and`yawol-controller`) can now be installed.\n\n1. Optional: Install `VerticalPodAutoscaler`. If installed you can enable the `VerticalPodAutoscaler` resources in the helm values.\n   1. [VPA install guide](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler#installation)\n2. Create a Kubernetes `Secret` that contains the contents of an `.openrc` file underneath the `cloudprovider.conf` key. \n   The `.openrc` credentials need the correct permission to be able to create instances and request floating IPs.\n\n**Note**: At most one of `domain-id` or `domain-name` and `project-id` or `project-name` must be provided.\n\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: cloud-provider-config\ntype: Opaque\nstringData:\n  cloudprovider.conf: |-\n    [Global]\n    auth-url=\"\u003cOS_AUTH_URL\u003e\"\n    domain-name=\"\u003cOS_USER_DOMAIN_NAME\u003e\"\n    domain-id=\"\u003cOS_DOMAIN_ID\u003e\"\n    # Deprecated (tenant-name): Please use project-name, only used if project-name is not set.\n    tenant-name=\"\u003cOS_PROJECT_NAME\u003e\"\n    project-name=\"\u003cOS_PROJECT_NAME\u003e\"\n    project-id=\"\u003cOS_PROJECT_ID\u003e\"\n    username=\"\u003cOS_USERNAME\u003e\"\n    password=\"\u003cOS_PASSWORD\u003e\"\n    region=\"\u003cOS_REGION_NAME\u003e\"\n    # Optional self-signed CA for OpenStack APIs\n    ca-file=\"/etc/ssl/myca.crt\"\n```\n\nAssuming you saved the secret as `secret-cloud-provider-config.yaml`, apply it with:\n\n```shell\nkubectl apply -f secret-cloud-provider-config.yaml\n```\n\n3. Configure the [Helm values](charts/yawol-controller/values.yaml) according to your OpenStack environment:\n   \n**Values for the yawol-cloud-controller**\n\n```yaml\n# the name of the Kubernetes secret we created in the previous step\n#\n# Placed in LoadBalancer.spec.infrastructure.authSecretRef.name\nyawolOSSecretName: cloud-provider-config\n\n# floating IP ID of the IP pool that yawol uses to request IPs\n#\n# Placed in LoadBalancer.spec.infrastructure.floatingNetID\nyawolFloatingID: \u003cfloating-id\u003e\n\n# OpenStack network ID in which the Load Balancer is placed\n#\n# Placed in LoadBalancer.spec.infrastructure.networkID\nyawolNetworkID: \u003cnetwork-id\u003e\n\n# OpenStack subnet ID in which the Load Balancer is placed.\n# If not set, the subnet is chosen automatically.\n#\n# Placed in LoadBalancer.spec.infrastructure.subnetID\nyawolSubnetID: \u003csubnet-id\u003e\n\n# default value for flavor that yawol Load Balancer instances should use\n# can be overridden by annotation\n#\n# Placed in LoadBalancer.spec.infrastructure.flavor.flavor_id\nyawolFlavorID: \u003cflavor-id\u003e\n\n# default value for ID of the image used for the Load Balancer instance\n# can be overridden by annotation\n#\n# Placed in LoadBalancer.spec.infrastructure.image.image_id\nyawolImageID: \u003cimage-id\u003e\n\n# default value for the AZ used for the Load Balancer instance\n# can be overridden by annotation. If not set, empty string is used.\n#\n# Placed in LoadBalancer.spec.infrastructure.availabilityZone\nyawolAvailabilityZone: \u003cavailability-zone\u003e\n```\n\n**Values for the yawol-controller**\n\n```yaml\n# URL/IP of the Kubernetes API server that contains the LoadBalancer resources\nyawolAPIHost: \u003capi-host\u003e\n```\n\n**To check out all available values have a look into the [Helm values](charts/yawol-controller/values.yaml)**\n\n\n4. With the values correctly configured, you can now install the Helm chart.\n\n```shell\nhelm install yawol ./charts/yawol-controller\n```\n\nThis will also install the CRDs needed by yawol.\n\nAfter successful installation, you can request `Services` of `type: LoadBalancer` and yawol will take care of creating an instance,\nallocating an IP, and updating the `Service` resource once the setup is ready.\n\nYou can also specify custom annotations on the `Service` to further control the  behavior of yawol.\n\n```yaml\napiVersion: v1\nkind: Service\nmetadata:\n  name: loadbalancer\n  annotations:\n    # Override the default  OpenStack image ID.\n    yawol.stackit.cloud/imageId: \"OS-imageId\"\n    # Override the default OpenStack machine flavor.\n    yawol.stackit.cloud/flavorId: \"OS-flavorId\"\n    # Overwrites the default openstack network for the loadbalancer.\n    # If this is set to a different network ID than defined as default in the yawol-cloud-controller\n    # the default from the yawol-cloud-controller will be added to the additionalNetworks.\n    yawol.stackit.cloud/defaultNetworkID: \"OS-networkID\"\n    # If set to true it do not add the default network ID from\n    # the yawol-cloud-controller to the additionalNetworks.\n    yawol.stackit.cloud/skipCloudControllerDefaultNetworkID: \"false\"\n    # Overwrites the projectID which is set by the secret.\n    # If not set the settings from the secret binding will be used.\n    # This field is immutable and can not be changed after the service is created.\n    yawol.stackit.cloud/projectID: \"OS-ProjectID\"\n    # Overwrites the openstack floating network for the loadbalancer.\n    yawol.stackit.cloud/floatingNetworkID: \"OS-floatingNetID\"\n    # Override the default OpenStack availability zone.\n    yawol.stackit.cloud/availabilityZone: \"OS-AZ\"\n    # Specify if this should be an internal LoadBalancer .\n    yawol.stackit.cloud/internalLB: \"false\"\n    # Run yawollet in debug mode.\n    yawol.stackit.cloud/debug: \"false\"\n    # Reference the name of the SSH key provided to OpenStack for debugging .\n    yawol.stackit.cloud/debugsshkey: \"OS-keyName\"\n    # Allows filtering services in cloud-controller.\n    # Deprecated: Use service.spec.loadBalancerClass instead.\n    yawol.stackit.cloud/className: \"test\"\n    # Specify the number of LoadBalancer machines to deploy (default 1).\n    yawol.stackit.cloud/replicas: \"3\"\n    # Specify an existing floating IP for yawol to use.\n    yawol.stackit.cloud/existingFloatingIP: \"193.148.175.46\"\n    # Specify the loadBalancerSourceRanges for the LoadBalancer like service.spec.loadBalancerSourceRanges (comma separated list).\n    # If service.spec.loadBalancerSourceRanges is set this annotation will NOT be used.\n    yawol.stackit.cloud/loadBalancerSourceRanges: \"10.10.10.0/24,10.10.20.0/24\"\n    # Enable/disable envoy support for proxy protocol.\n    yawol.stackit.cloud/tcpProxyProtocol: \"false\"\n    # Defines proxy protocol ports (comma separated list).\n    yawol.stackit.cloud/tcpProxyProtocolPortsFilter: \"80,443\"\n    # Enables log forwarding.\n    yawol.stackit.cloud/logForward: \"true\"\n    # Defines loki URL for the log forwarding.\n    yawol.stackit.cloud/logForwardLokiURL: \"http://example.com:3100/loki/api/v1/push\"\n    # Defines proxy URL for the log forwarding.\n    yawol.stackit.cloud/logForwardProxyURL: \"http://proxy.example.com:8000\"\n    # Defines labels that are added when forwarding logs\n    # The prefix \"logging.yawol.stackit.cloud/\" will be trimmed\n    # and only \"foo\": \"bar\" will be added as a label\n    logging.yawol.stackit.cloud/foo: \"bar\"\n    # Setting multiple labels is also supported.\n    logging.yawol.stackit.cloud/env: \"testing\"\n    # Defines the TCP idle Timeout as duration, default is 1h.\n    # Make sure there is a valid unit (like \"s\", \"m\", \"h\"), otherwise this option is ignored.\n    yawol.stackit.cloud/tcpIdleTimeout: \"5m30s\"\n    # Defines the UDP idle Timeout as duration, default is 1m.\n    # Make sure there is a valid unit (like \"s\", \"m\", \"h\"), otherwise this option is ignored.\n    yawol.stackit.cloud/udpIdleTimeout: \"5m\"\n    # Defines the openstack server group policy for a LoadBalancer.\n    # Can be 'affinity', 'anti-affinity' 'soft-affinity', 'soft-anti-affinity' depending on the OpenStack Infrastructure.\n    # If not set openstack server group is disabled.\n    yawol.stackit.cloud/serverGroupPolicy: anti-affinity\n    # Defines additional openstack networks for the loadbalancer (comma separated list).\n    yawol.stackit.cloud/additionalNetworks: \"OS-networkID1,OS-networkID2\"\n```\n\nTo create a first LoadBalancer you can create a nginx deployment with a `Service` of type `LoadBalancer`:\n\n```shell\nkubectl create deploy --image nginx --port 80 nginx\nkubectl expose deployment nginx --port 80 --type LoadBalancer\n```\n\n## Development\n\nSee the [development guide](docs/development.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackitcloud%2Fyawol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackitcloud%2Fyawol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackitcloud%2Fyawol/lists"}