From 395994ebc1a0c1f1d226d56dc3fde5111990e9ac Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Tue, 23 Jan 2024 14:57:19 +0200 Subject: [PATCH] Add support for APISIX Gateway --- docs/services/apisix-gateway.md | 87 +++++++++++++++++++++++++++++++ docs/supported-services.md | 1 + templates/group_vars_mash_servers | 60 +++++++++++++++++++++ templates/requirements.yml | 4 ++ templates/setup.yml | 4 ++ 5 files changed, 156 insertions(+) create mode 100644 docs/services/apisix-gateway.md diff --git a/docs/services/apisix-gateway.md b/docs/services/apisix-gateway.md new file mode 100644 index 0000000..d6d9a57 --- /dev/null +++ b/docs/services/apisix-gateway.md @@ -0,0 +1,87 @@ +# APISIX Gateway + +[APISIX Gateway](https://apisix.apache.org/docs/apisix/getting-started/README/) is an [API Gateway](https://apisix.apache.org/docs/apisix/terminology/api-gateway/) and Ingress Controller. + +APISIX Gateway has a complex [architecture](https://apisix.apache.org/docs/apisix/architecture-design/apisix/) in which APISIX can serve multiple roles (data plane, control plane). There are different [deployment modes](https://apisix.apache.org/docs/apisix/deployment-modes/) for achieving a more decoupled setup. + +What we're configuring here is a `traditional` deployment in which one APISIX instance acts as both the data plane and the control plane. +By tweaking the configuration, you may be able to install multiple instances (on separate machines), each serving a different role. This is beyond the scope of this documentation page. + + +## Dependencies + +This service requires the following other services: + +- a [Traefik](traefik.md) reverse-proxy server +- an [etcd](etcd.md) key-value store + + +## Configuration + +To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process: + +```yaml +######################################################################## +# # +# apisix_gateway # +# # +######################################################################## + +apisix_gateway_enabled: true + +# Configure the hostname and path at which the API would be exposed +apisix_gateway_hostname: api.example.com +apisix_gateway_path_prefix: /api + +apisix_gateway_config_deployment_admin_admin_key: + - name: admin1 + key: secret-api-key-here + role: admin + - name: viewer1 + key: secret-api-key-here + role: viewer + +# You may also wish to enable the Admin API. +# +# If you'd be administrating APISIX via another service +# (e.g. APISIX Dashboard, which manipulates the etcd database directly), +# then enabling this Admin API is not strictly required. +apisix_gateway_container_labels_admin_enabled: true +apisix_gateway_container_labels_admin_hostname: admin.api.example.com +apisix_gateway_container_labels_admin_path_prefix: / + +######################################################################## +# # +# /apisix_gateway # +# # +######################################################################## +``` + +If you'd like to do something more advanced, the [`ansible-role-apisix-gateway` Ansible role](https://github.com/mother-of-all-self-hosting/ansible-role-apisix-gateway) is very configurable and should not get in your way of exposing ports or configuring arbitrary settings. + +Take a look at [its `default/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-apisix-gateway/blob/main/defaults/main.yml) for available Ansible variables you can use in your own `vars.yml` configuration file. + +### URL + +In the example configuration above, we configure APISIX to expose 2 services: + +- Gateway API, to be reachable at `https://api.example.com/api` +- [Admin API](https://apisix.apache.org/docs/apisix/admin-api/), to be reachable at `https://api.example.com/api` + +Path prefixes default to `/` for all services, so if you don't like the example above (using `/api`), consider removing the path prefix variables. + +## Usage + +After installation, you can send API requests to your API gateway (as specified in `apisix_gateway_hostname` and `apisix_gateway_path_prefix`). + +Example: `curl https://api.example.com/api` + +Since no routes are configured by default, you'd receive 404 requests. To configure routes, either use the Admin API (described below) or install [APISIX dashboard](./apisix-dashboard.md) to administrate APISIX using a web UI. + +If you've enabled the [Admin API](https://apisix.apache.org/docs/apisix/admin-api/) (`apisix_gateway_container_labels_admin_enabled: true`), you will also be able to manage the APISIX configuration (managing routes, upstreams, etc.) by sending API requests to the Admin API URL (as specified in `apisix_gateway_container_labels_admin_hostname` and `apisix_gateway_container_labels_admin_path_prefix`). + +Example: `curl -H 'X-API-KEY: YOUR_SECRET_API_KEY_HERE' https://admin.api.example.com/apisix/admin/routes` + +## Recommended other services + +- [APISIX dashboard](apisix-dashboard.md) - a dashboard (web UI) for APISIX diff --git a/docs/supported-services.md b/docs/supported-services.md index 5f954e4..7e4054c 100644 --- a/docs/supported-services.md +++ b/docs/supported-services.md @@ -4,6 +4,7 @@ | ------------------------------ | ------------------------------------- | ------------- | | [AUX](https://github.com/mother-of-all-self-hosting/ansible-role-aux) | Auxiliary file/directory management on your server via Ansible | [Link](services/auxiliary.md) | | [AdGuard Home](https://adguard.com/en/adguard-home/overview.html/) | A network-wide DNS software for blocking ads & tracking | [Link](services/adguard-home.md) | +| [APISIX Gateway](https://apisix.apache.org/docs/apisix/getting-started/README/) | An API Gateway, Ingress Controller, etc | [Link](services/apisix-gateway.md) | | [Appsmith](https://www.appsmith.com/) | Platform for building and deploying custom internal tools and applications without writing code | [Link](services/appsmith.md) | | [Authelia](https://www.authelia.com/) | An open-source authentication and authorization server that can work as a companion to [common reverse proxies](https://www.authelia.com/overview/prologue/supported-proxies/) (like [Traefik](traefik.md) frequently used by this playbook) | [Link](services/authelia.md) | | [authentik](https://goauthentik.io/) | An open-source Identity Provider focused on flexibility and versatility. | [Link](services/authentik.md) | diff --git a/templates/group_vars_mash_servers b/templates/group_vars_mash_servers index 7587174..107a94d 100644 --- a/templates/group_vars_mash_servers +++ b/templates/group_vars_mash_servers @@ -159,6 +159,11 @@ mash_playbook_devture_systemd_service_manager_services_list_auto_itemized: {{ ({'name': (adguard_home_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'adguard-home']} if adguard_home_enabled else omit) }} # /role-specific:adguard_home + # role-specific:apisix_gateway + - |- + {{ ({'name': (apisix_gateway_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'apisix-gateway']} if apisix_gateway_enabled else omit) }} + # /role-specific:apisix_gateway + # role-specific:appsmith - |- {{ ({'name': (appsmith_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'appsmith']} if appsmith_enabled else omit) }} @@ -1096,6 +1101,61 @@ adguard_home_container_labels_traefik_tls_certResolver: "{{ devture_traefik_cert +# role-specific:apisix_gateway +######################################################################## +# # +# apisix_gateway # +# # +######################################################################## + +apisix_gateway_enabled: false + +apisix_gateway_identifier: "{{ mash_playbook_service_identifier_prefix }}apisix-gateway" + +apisix_gateway_uid: "{{ mash_playbook_uid }}" +apisix_gateway_gid: "{{ mash_playbook_gid }}" + +apisix_gateway_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}apisix-gateway" + +apisix_gateway_container_additional_networks_auto: | + {{ + ([mash_playbook_reverse_proxyable_services_additional_network] if (mash_playbook_reverse_proxyable_services_additional_network and apisix_gateway_container_labels_traefik_enabled) else []) + }} + +apisix_gateway_container_labels_traefik_enabled: "{{ mash_playbook_traefik_labels_enabled }}" +apisix_gateway_container_labels_traefik_docker_network: "{{ mash_playbook_reverse_proxyable_services_additional_network }}" +apisix_gateway_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}" +apisix_gateway_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}" + +# role-specific:etcd +apisix_gateway_config_deployment_etcd_host: | + {{ + ([('http://' + etcd_identifier + ':2379')] if etcd_enabled else []) + }} + +apisix_gateway_config_deployment_etcd_user: "{{ ('root' if (etcd_enabled and not etcd_environment_variable_allow_none_authentication) else '') }}" +apisix_gateway_config_deployment_etcd_password: "{{ (etcd_environment_variable_etcd_root_password if (etcd_enabled and not etcd_environment_variable_allow_none_authentication) else '') }}" + +apisix_gateway_container_additional_networks_custom: | + {{ + ([etcd_container_network] if etcd_enabled else []) + }} + +apisix_gateway_systemd_required_systemd_services_list_auto: | + {{ + ([(etcd_identifier + '.service')] if etcd_enabled else []) + }} +# /role-specific:etcd + +######################################################################## +# # +# /apisix_gateway # +# # +######################################################################## +# /role-specific:apisix_gateway + + + # role-specific:appsmith ######################################################################## # # diff --git a/templates/requirements.yml b/templates/requirements.yml index 6216f78..2eb3d6c 100644 --- a/templates/requirements.yml +++ b/templates/requirements.yml @@ -8,6 +8,10 @@ version: v1.9.50-0 name: appsmith activation_prefix: appsmith_ +- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-apisix-gateway.git + version: v3.8.0-0 + name: apisix_gateway + activation_prefix: apisix_gateway_ - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-authelia.git version: v4.37.5-1 name: authelia diff --git a/templates/setup.yml b/templates/setup.yml index 9e8e21e..f54e1d3 100644 --- a/templates/setup.yml +++ b/templates/setup.yml @@ -98,6 +98,10 @@ - role: galaxy/appsmith # /role-specific:appsmith + # role-specific:apisix_gateway + - role: galaxy/apisix_gateway + # /role-specific:apisix_gateway + # role-specific:authelia - role: galaxy/authelia # /role-specific:authelia