opcycle/swarm-ingress repository overview

⁠Ingress Service for Docker Swarm

Swarm Ingress OpenResty is a ingress service for Docker in Swarm mode that makes deploying microservices easy. It configures itself automatically and dynamically using services labels.

⁠Docker Images

• All images based on openresty/openresty:jammy
• GitHub actions builds⁠
• Docker Hub⁠

⁠Features

• No external load balancer or config files needed making for easy deployments
• Integrated TLS decryption for services which provide a certificate and key
• Automatic service discovery and load balancing handled by Docker
• Scaled and maintained by the Swarm for high resilience and performance
• On the fly SSL registration and renewal
• Support multiple replicas of service. SSL certificates stored in Redis server

⁠SSL registration and renewal

This OpenResty plugin automatically and transparently issues SSL certificates from Let's Encrypt as requests are received using lua-resty-auto-ssl⁠ plugin. It works like:

• A SSL request for a SNI hostname is received.
• If the system already has a SSL certificate for that domain, it is immediately returned (with OCSP stapling).
• If the system does not yet have an SSL certificate for this domain, it issues a new SSL certificate from Let's Encrypt. Domain validation is handled for you. After receiving the new certificate (usually within a few seconds), the new certificate is saved, cached, and returned to the client (without dropping the original request).

⁠Run the Service

The Ingress service acts as a reverse proxy in your cluster. It exposes port 80 and 443 to the public an redirects all requests to the correct service in background. It is important that the ingress service can reach other services via the Swarm network (that means they must share a network).

Create network:

docker network create --driver overlay ingress-routing

Deploy swarm stack:

docker stack deploy -c examples/ingress-stack.yml ingress

The ingress service should be scaled to multiple nodes to prevent short outages when the node with the ingress servic becomes unresponsive. By default configured 2 replicas

⁠Register a Service for Ingress

A service can easily be configured using ingress. You must simply provide a label ingress.host which determines the hostname under wich the service should be publicly available.

⁠Configuration Labels

Additionally to the hostname you can also map another port and path of your service. By default a request would be redirected to http://service-name:80/.

⁠Run a Service with Enabled Ingress

It is important to run the service which should be used for ingress that it shares a network.

To start a service with ingress simply pass the required labels on creation.

docker service create --name my-service \
  --network ingress-routing \
  --label ingress.host=my-service.company.tld \
  --label ingress.ssl=yes \
  --label ingress.ssl_redirect=yes \
  nginx

It is also possible to later add a service to ingress using service update.

docker service update \
  --label-add ingress.host=my-service.company.tld \
  --label-add ingress.port=8080 \
  my-service

⁠Contributing

We'd love for you to contribute to this container. You can request new features by creating an issue⁠, or submit a pull request⁠ with your contribution.

⁠Issues

If you encountered a problem running this container, you can file an issue. For us to provide better support, be sure to include the following information in your issue:

• Host OS and version
• Docker version
• Output of docker info
• Version of this container
• The command you used to run the container, and any relevant output you saw (masking any sensitive information)