ci: add doc deployment
This commit is contained in:
GitHub
55
.github/workflows/deploy-docs.yml
vendored
Normal file
55
.github/workflows/deploy-docs.yml
vendored
Normal file
@@ -0,0 +1,55 @@
|
||||
name: Deploy Documenation site to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ['main']
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- '.github/workflows/deploy-docs.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: 'pages'
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
- name: Setup Ruby
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: '3.2'
|
||||
bundler-cache: true
|
||||
cache-version: 0
|
||||
working-directory: docs
|
||||
- name: Setup Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v2
|
||||
- name: Build with Jekyll
|
||||
working-directory: docs
|
||||
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
|
||||
env:
|
||||
JEKYLL_ENV: production
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v1
|
||||
with:
|
||||
path: 'docs/_site/'
|
||||
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v1
|
||||
3
docs/.gitignore
vendored
Normal file
3
docs/.gitignore
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
_site
|
||||
.sass-cache
|
||||
.jekyll-metadata
|
||||
24
docs/404.html
Normal file
24
docs/404.html
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
||||
<style type="text/css" media="screen">
|
||||
.container {
|
||||
margin: 10px auto;
|
||||
max-width: 600px;
|
||||
text-align: center;
|
||||
}
|
||||
h1 {
|
||||
margin: 30px 0;
|
||||
font-size: 4em;
|
||||
line-height: 1;
|
||||
letter-spacing: -1px;
|
||||
}
|
||||
</style>
|
||||
|
||||
<div class="container">
|
||||
<h1>404</h1>
|
||||
|
||||
<p><strong>Page not found :(</strong></p>
|
||||
<p>The requested page could not be found.</p>
|
||||
</div>
|
||||
43
docs/Gemfile
Normal file
43
docs/Gemfile
Normal file
@@ -0,0 +1,43 @@
|
||||
source "https://rubygems.org"
|
||||
|
||||
# Hello! This is where you manage which Jekyll version is used to run.
|
||||
# When you want to use a different version, change it below, save the
|
||||
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
|
||||
#
|
||||
# bundle exec jekyll serve
|
||||
#
|
||||
# This will help ensure the proper Jekyll version is running.
|
||||
# Happy Jekylling!
|
||||
gem "jekyll", "~> 3.10.0"
|
||||
|
||||
# This is the default theme for new Jekyll sites. You may change this to anything you like.
|
||||
gem "minima", "~> 2.0"
|
||||
|
||||
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
|
||||
# uncomment the line below. To upgrade, run `bundle update github-pages`.
|
||||
# gem "github-pages", group: :jekyll_plugins
|
||||
|
||||
# If you have any plugins, put them here!
|
||||
group :jekyll_plugins do
|
||||
gem "jekyll-feed", "~> 0.6"
|
||||
end
|
||||
|
||||
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
|
||||
# and associated library.
|
||||
platforms :mingw, :x64_mingw, :mswin, :jruby do
|
||||
gem "tzinfo", ">= 1", "< 3"
|
||||
gem "tzinfo-data"
|
||||
end
|
||||
|
||||
# Performance-booster for watching directories on Windows
|
||||
gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?
|
||||
|
||||
# kramdown v2 ships without the gfm parser by default. If you're using
|
||||
# kramdown v1, comment out this line.
|
||||
gem "kramdown-parser-gfm"
|
||||
|
||||
# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
|
||||
# do not have a Java counterpart.
|
||||
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
|
||||
gem "just-the-docs"
|
||||
|
||||
116
docs/Gemfile.lock
Normal file
116
docs/Gemfile.lock
Normal file
@@ -0,0 +1,116 @@
|
||||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
addressable (2.8.7)
|
||||
public_suffix (>= 2.0.2, < 7.0)
|
||||
colorator (1.1.0)
|
||||
concurrent-ruby (1.3.3)
|
||||
csv (3.3.0)
|
||||
em-websocket (0.5.3)
|
||||
eventmachine (>= 0.12.9)
|
||||
http_parser.rb (~> 0)
|
||||
eventmachine (1.2.7)
|
||||
ffi (1.17.0)
|
||||
ffi (1.17.0-aarch64-linux-gnu)
|
||||
ffi (1.17.0-aarch64-linux-musl)
|
||||
ffi (1.17.0-arm-linux-gnu)
|
||||
ffi (1.17.0-arm-linux-musl)
|
||||
ffi (1.17.0-arm64-darwin)
|
||||
ffi (1.17.0-x86-linux-gnu)
|
||||
ffi (1.17.0-x86-linux-musl)
|
||||
ffi (1.17.0-x86_64-darwin)
|
||||
ffi (1.17.0-x86_64-linux-gnu)
|
||||
ffi (1.17.0-x86_64-linux-musl)
|
||||
forwardable-extended (2.6.0)
|
||||
http_parser.rb (0.8.0)
|
||||
i18n (1.14.5)
|
||||
concurrent-ruby (~> 1.0)
|
||||
jekyll (3.10.0)
|
||||
addressable (~> 2.4)
|
||||
colorator (~> 1.0)
|
||||
csv (~> 3.0)
|
||||
em-websocket (~> 0.5)
|
||||
i18n (>= 0.7, < 2)
|
||||
jekyll-sass-converter (~> 1.0)
|
||||
jekyll-watch (~> 2.0)
|
||||
kramdown (>= 1.17, < 3)
|
||||
liquid (~> 4.0)
|
||||
mercenary (~> 0.3.3)
|
||||
pathutil (~> 0.9)
|
||||
rouge (>= 1.7, < 4)
|
||||
safe_yaml (~> 1.0)
|
||||
webrick (>= 1.0)
|
||||
jekyll-feed (0.17.0)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-include-cache (0.2.1)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-sass-converter (1.5.2)
|
||||
sass (~> 3.4)
|
||||
jekyll-seo-tag (2.8.0)
|
||||
jekyll (>= 3.8, < 5.0)
|
||||
jekyll-watch (2.2.1)
|
||||
listen (~> 3.0)
|
||||
just-the-docs (0.8.2)
|
||||
jekyll (>= 3.8.5)
|
||||
jekyll-include-cache
|
||||
jekyll-seo-tag (>= 2.0)
|
||||
rake (>= 12.3.1)
|
||||
kramdown (2.4.0)
|
||||
rexml
|
||||
kramdown-parser-gfm (1.1.0)
|
||||
kramdown (~> 2.0)
|
||||
liquid (4.0.4)
|
||||
listen (3.9.0)
|
||||
rb-fsevent (~> 0.10, >= 0.10.3)
|
||||
rb-inotify (~> 0.9, >= 0.9.10)
|
||||
mercenary (0.3.6)
|
||||
minima (2.5.1)
|
||||
jekyll (>= 3.5, < 5.0)
|
||||
jekyll-feed (~> 0.9)
|
||||
jekyll-seo-tag (~> 2.1)
|
||||
pathutil (0.16.2)
|
||||
forwardable-extended (~> 2.6)
|
||||
public_suffix (6.0.1)
|
||||
rake (13.2.1)
|
||||
rb-fsevent (0.11.2)
|
||||
rb-inotify (0.11.1)
|
||||
ffi (~> 1.0)
|
||||
rexml (3.3.2)
|
||||
strscan
|
||||
rouge (3.30.0)
|
||||
safe_yaml (1.0.5)
|
||||
sass (3.7.4)
|
||||
sass-listen (~> 4.0.0)
|
||||
sass-listen (4.0.0)
|
||||
rb-fsevent (~> 0.9, >= 0.9.4)
|
||||
rb-inotify (~> 0.9, >= 0.9.7)
|
||||
strscan (3.1.0)
|
||||
wdm (0.1.1)
|
||||
webrick (1.8.1)
|
||||
|
||||
PLATFORMS
|
||||
aarch64-linux-gnu
|
||||
aarch64-linux-musl
|
||||
arm-linux-gnu
|
||||
arm-linux-musl
|
||||
arm64-darwin
|
||||
ruby
|
||||
x86-linux-gnu
|
||||
x86-linux-musl
|
||||
x86_64-darwin
|
||||
x86_64-linux-gnu
|
||||
x86_64-linux-musl
|
||||
|
||||
DEPENDENCIES
|
||||
http_parser.rb (~> 0.6.0)
|
||||
jekyll (~> 3.10.0)
|
||||
jekyll-feed (~> 0.6)
|
||||
just-the-docs
|
||||
kramdown-parser-gfm
|
||||
minima (~> 2.0)
|
||||
tzinfo (>= 1, < 3)
|
||||
tzinfo-data
|
||||
wdm (~> 0.1.0)
|
||||
|
||||
BUNDLED WITH
|
||||
2.5.16
|
||||
70
docs/_config.yml
Normal file
70
docs/_config.yml
Normal file
@@ -0,0 +1,70 @@
|
||||
# Welcome to Jekyll!
|
||||
#
|
||||
# This config file is meant for settings that affect your whole blog, values
|
||||
# which you are expected to set up once and rarely edit after that. If you find
|
||||
# yourself editing this file very often, consider using Jekyll's data files
|
||||
# feature for the data you need to update frequently.
|
||||
#
|
||||
# For technical reasons, this file is *NOT* reloaded automatically when you use
|
||||
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
|
||||
|
||||
# Site settings
|
||||
# These are used to personalize your new site. If you look in the HTML files,
|
||||
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
|
||||
# You can create any custom variable you would like, and they will be accessible
|
||||
# in the templates via {{ site.myvariable }}.
|
||||
title: Goma Gateway
|
||||
email: hi@jonaskaninda.com
|
||||
description: >- # this means to ignore newlines until "baseurl:"
|
||||
Goma Gateway is a lightweight API Gateway and Reverse Proxy.
|
||||
|
||||
baseurl: "/" # the subpath of your site, e.g. /blog
|
||||
url: "jkaninda.github.io/goma-gateway" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
twitter_username: jonaskaninda
|
||||
github_username: jkaninda
|
||||
|
||||
callouts_level: quiet
|
||||
callouts:
|
||||
highlight:
|
||||
color: yellow
|
||||
important:
|
||||
title: Important
|
||||
color: blue
|
||||
new:
|
||||
title: New
|
||||
color: green
|
||||
note:
|
||||
title: Note
|
||||
color: purple
|
||||
warning:
|
||||
title: Warning
|
||||
color: red
|
||||
# Build settings
|
||||
markdown: kramdown
|
||||
theme: just-the-docs
|
||||
plugins:
|
||||
- jekyll-feed
|
||||
aux_links:
|
||||
'GitHub Repository':
|
||||
- https://github.com/jkaninda/goma-gateway
|
||||
|
||||
nav_external_links:
|
||||
- title: GitHub Repository
|
||||
url: https://github.com/jkaninda/goma-gateway
|
||||
|
||||
footer_content: >-
|
||||
Copyright © 2024 <a target="_blank" href="https://www.jonaskaninda.com">Jonas Kaninda</a>.
|
||||
Distributed under the <a href="https://github.com/jkaninda/pg-bkup/tree/main/LICENSE">MIT License.</a><br>
|
||||
Something missing, unclear or not working? Open <a href="https://github.com/jkaninda/pg-bkup/issues">an issue</a>.
|
||||
|
||||
# Exclude from processing.
|
||||
# The following items will not be processed, by default. Create a custom list
|
||||
# to override the default setting.
|
||||
# exclude:
|
||||
# - Gemfile
|
||||
# - Gemfile2.lock
|
||||
# - node_modules
|
||||
# - vendor/bundle/
|
||||
# - vendor/cache/
|
||||
# - vendor/gems/
|
||||
# - vendor/ruby/
|
||||
BIN
docs/favicon.ico
Normal file
BIN
docs/favicon.ico
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.1 KiB |
66
docs/index.md
Normal file
66
docs/index.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Overview
|
||||
layout: home
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# About Goma Gateway
|
||||
{:.no_toc}
|
||||
Goma Gateway is a lightweight API Gateway and Reverse Proxy.
|
||||
|
||||
It comes with a lot of integrated features, such as:
|
||||
|
||||
- Reverse proxy
|
||||
- RESTfull API Gateway management
|
||||
- Domain/host based request routing
|
||||
- Multi domain request routing
|
||||
- Cross-Origin Resource Sharing (CORS)
|
||||
- Backend errors interceptor
|
||||
- Authentication middleware
|
||||
- JWT `client authorization based on the result of a request`
|
||||
- Basic-Auth
|
||||
- Rate limiting
|
||||
- In-Memory Token Bucket based
|
||||
- In-Memory client IP based
|
||||
|
||||
Declare your routes and middlewares as code.
|
||||
|
||||
We are open to receiving stars, PRs, and issues!
|
||||
|
||||
|
||||
{: .fs-6 .fw-300 }
|
||||
|
||||
---
|
||||
|
||||
The [jkaninda/goma-gateway](https://hub.docker.com/r/jkaninda/goma-gateway) Docker image can be deployed on Docker, Docker Swarm and Kubernetes.
|
||||
|
||||
It also supports database __encryption__ using GPG.
|
||||
|
||||
|
||||
|
||||
## Available image registries
|
||||
|
||||
This Docker image is published to both Docker Hub and the GitHub container registry.
|
||||
Depending on your preferences and needs, you can reference both `jkaninda/goma-gateway` as well as `ghcr.io/jkaninda/goma-gateway`:
|
||||
|
||||
```
|
||||
docker pull jkaninda/goma-gateway
|
||||
docker pull ghcr.io/jkaninda/goma-gateway
|
||||
```
|
||||
|
||||
Documentation references Docker Hub, but all examples will work using ghcr.io just as well.
|
||||
|
||||
## Supported Engines
|
||||
|
||||
This image is developed and tested against the Docker CE engine exclusively.
|
||||
While it may work against different implementations, there are no guarantees about support for non-Docker engines.
|
||||
|
||||
## References
|
||||
|
||||
We decided to publish this image as a simpler and more lightweight alternative because of the following requirements:
|
||||
|
||||
- The original image is based on `Alpine` and requires additional tools, making it heavy.
|
||||
- This image is written in Go.
|
||||
- `arm64` and `arm/v7` architectures are supported.
|
||||
- Docker in Swarm mode is supported.
|
||||
- Kubernetes is supported.
|
||||
183
docs/quickstart/configuration.md
Normal file
183
docs/quickstart/configuration.md
Normal file
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: Configuration
|
||||
layout: default
|
||||
parent: Quickstart
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
### 1. Initialize configuration
|
||||
|
||||
```shell
|
||||
docker run --rm --name goma-gateway \
|
||||
-v "${PWD}/config:/config" \
|
||||
jkaninda/goma-gateway config init --output /config/config.yml
|
||||
```
|
||||
|
||||
### 3. Start server with a custom config
|
||||
```shell
|
||||
docker run --rm --name goma-gateway \
|
||||
-v "${PWD}/config:/config" \
|
||||
-p 80:80 \
|
||||
jkaninda/goma-gateway server --config /config/config.yml
|
||||
```
|
||||
### 4. Healthcheck
|
||||
|
||||
- Goma Gateway readiness: `/readyz`
|
||||
- Routes health check: `/healthz`
|
||||
|
||||
## Customize configuration file
|
||||
|
||||
Example of a configuration file
|
||||
```yaml
|
||||
## Goma - simple lightweight API Gateway and Reverse Proxy.
|
||||
# Goma Gateway configurations
|
||||
gateway:
|
||||
########## Global settings
|
||||
listenAddr: 0.0.0.0:80
|
||||
# Proxy write timeout
|
||||
writeTimeout: 15
|
||||
# Proxy read timeout
|
||||
readTimeout: 15
|
||||
# Proxy idle timeout
|
||||
idleTimeout: 60
|
||||
# Proxy rate limit, it's In-Memory IP based
|
||||
# Distributed Rate Limiting for Token based across multiple instances is not yet integrated
|
||||
rateLimiter: 0
|
||||
accessLog: "/dev/Stdout"
|
||||
errorLog: "/dev/stderr"
|
||||
## Returns backend route healthcheck errors
|
||||
disableRouteHealthCheckError: false
|
||||
# Disable display routes on start
|
||||
disableDisplayRouteOnStart: false
|
||||
# disableKeepAlive allows enabling and disabling KeepALive server
|
||||
disableKeepAlive: false
|
||||
# interceptErrors intercepts backend errors based on defined the status codes
|
||||
interceptErrors:
|
||||
- 405
|
||||
- 500
|
||||
# - 400
|
||||
# Proxy Global HTTP Cors
|
||||
cors:
|
||||
# Global routes cors for all routes
|
||||
origins:
|
||||
- http://localhost:8080
|
||||
- https://example.com
|
||||
# Global routes cors headers for all routes
|
||||
headers:
|
||||
Access-Control-Allow-Headers: 'Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id'
|
||||
Access-Control-Allow-Credentials: 'true'
|
||||
Access-Control-Max-Age: 1728000
|
||||
##### Define routes
|
||||
routes:
|
||||
# Example of a route | 1
|
||||
- name: Public
|
||||
# host Domain/host based request routing
|
||||
host: "" # Host is optional
|
||||
path: /public
|
||||
## Rewrite a request path
|
||||
# e.g rewrite: /store to /
|
||||
rewrite: /healthz
|
||||
destination: https://example.com
|
||||
#DisableHeaderXForward Disable X-forwarded header.
|
||||
# [X-Forwarded-Host, X-Forwarded-For, Host, Scheme ]
|
||||
# It will not match the backend route, by default, it's disabled
|
||||
disableHeaderXForward: false
|
||||
# Internal health check
|
||||
healthCheck: '' #/internal/health/ready
|
||||
# Route Cors, global cors will be overridden by route
|
||||
cors:
|
||||
# Route Origins Cors, global cors will be overridden by route
|
||||
origins:
|
||||
- https://dev.example.com
|
||||
- http://localhost:3000
|
||||
- https://example.com
|
||||
# Route Cors headers, route will override global cors
|
||||
headers:
|
||||
Access-Control-Allow-Methods: 'GET'
|
||||
Access-Control-Allow-Headers: 'Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id'
|
||||
Access-Control-Allow-Credentials: 'true'
|
||||
Access-Control-Max-Age: 1728000
|
||||
##### Define route middlewares from middlewares names
|
||||
## The name must be unique
|
||||
## List of middleware name
|
||||
middlewares:
|
||||
- api-forbidden-paths
|
||||
- basic-auth
|
||||
# Example of a route | 2
|
||||
- name: Authentication service
|
||||
path: /auth
|
||||
rewrite: /
|
||||
destination: 'http://security-service:8080'
|
||||
healthCheck: /internal/health/ready
|
||||
cors: {}
|
||||
middlewares:
|
||||
- api-forbidden-paths
|
||||
# Example of a route | 3
|
||||
- name: Basic auth
|
||||
path: /protected
|
||||
rewrite: /
|
||||
destination: 'http://notification-service:8080'
|
||||
healthCheck:
|
||||
cors: {}
|
||||
middlewares: []
|
||||
|
||||
#Defines proxy middlewares
|
||||
# middleware name must be unique
|
||||
middlewares:
|
||||
# Enable Basic auth authorization based
|
||||
- name: basic-auth
|
||||
# Authentication types | jwt, basic, OAuth
|
||||
type: basic
|
||||
paths:
|
||||
- /user
|
||||
- /admin
|
||||
- /account
|
||||
rule:
|
||||
username: admin
|
||||
password: admin
|
||||
#Enables JWT authorization based on the result of a request and continues the request.
|
||||
- name: google-auth
|
||||
# Authentication types | jwt, basic, OAuth
|
||||
# jwt authorization based on the result of backend's response and continue the request when the client is authorized
|
||||
type: jwt
|
||||
# Paths to protect
|
||||
paths:
|
||||
- /protected-access
|
||||
- /example-of-jwt
|
||||
#- /* or wildcard path
|
||||
rule:
|
||||
# This is an example URL
|
||||
url: https://www.googleapis.com/auth/userinfo.email
|
||||
# Required headers, if not present in the request, the proxy will return 403
|
||||
requiredHeaders:
|
||||
- Authorization
|
||||
#Sets the request variable to the given value after the authorization request completes.
|
||||
#
|
||||
# Add header to the next request from AuthRequest header, depending on your requirements
|
||||
# Key is AuthRequest's response header Key, and value is Request's header Key
|
||||
# In case you want to get headers from the Authentication service and inject them into the next request's headers
|
||||
#Sets the request variable to the given value after the authorization request completes.
|
||||
#
|
||||
# Add header to the next request from AuthRequest header, depending on your requirements
|
||||
# Key is AuthRequest's response header Key, and value is Request's header Key
|
||||
# In case you want to get headers from the Authentication service and inject them into the next request's headers
|
||||
headers:
|
||||
userId: X-Auth-UserId
|
||||
userCountryId: X-Auth-UserCountryId
|
||||
# In case you want to get headers from the Authentication service and inject them to the next request's params
|
||||
params:
|
||||
userCountryId: countryId
|
||||
# The server will return 404
|
||||
- name: api-forbidden-paths
|
||||
type: access
|
||||
## Forbidden paths
|
||||
paths:
|
||||
- /swagger-ui/*
|
||||
- /v2/swagger-ui/*
|
||||
- /api-docs/*
|
||||
- /internal/*
|
||||
- /actuator/*
|
||||
```
|
||||
9
docs/quickstart/index.md
Normal file
9
docs/quickstart/index.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Quickstart
|
||||
layout: default
|
||||
nav_order: 3
|
||||
has_children: true
|
||||
---
|
||||
|
||||
## Quickstart
|
||||
|
||||
179
docs/quickstart/middleware.md
Normal file
179
docs/quickstart/middleware.md
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
title: Middleware
|
||||
layout: default
|
||||
parent: Quickstart
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
|
||||
## Middlewares
|
||||
|
||||
Middleware is a function executed before (or after) the route callback.
|
||||
|
||||
This is a great way to add API authentication checks, or to validate that the user has permission to access the route.
|
||||
|
||||
With Goma you can create your middleware based on the type you want and apply it on your routes
|
||||
|
||||
Goma Gateway supports :
|
||||
|
||||
- Authentication middleware
|
||||
- JWT `HTTP Bearer Token`
|
||||
- Basic-Auth
|
||||
- Rate limiting middleware
|
||||
- In-Memory Token Bucket based
|
||||
- In-Memory client IP based
|
||||
- Access middleware
|
||||
|
||||
### BasicAuth middleware
|
||||
The BasicAuth middleware grants access to route to authorized users only.
|
||||
|
||||
### Configuration Options
|
||||
|
||||
You don't need to hash your password (MD5, SHA1, or BCrypt), Goma gateway will handle it.
|
||||
|
||||
You need just to provide the username and password
|
||||
|
||||
Example of basic-auth middleware
|
||||
```yaml
|
||||
middlewares:
|
||||
# Middleware name
|
||||
- name: basic-auth
|
||||
# Middleware type
|
||||
type: basic
|
||||
# Paths to apply middleware
|
||||
paths:
|
||||
- /user
|
||||
- /admin
|
||||
- /account
|
||||
rule:
|
||||
username: admin
|
||||
password: admin
|
||||
```
|
||||
|
||||
### JWT middleware
|
||||
|
||||
As BasicAuth, JWT middleware grants also access to route to authorized users only.
|
||||
It implements client authorization based on the result of a request.
|
||||
|
||||
If the request returns a 200 response code, access is allowed.
|
||||
If it returns 401 or 403, the access is denied with the corresponding error code. Any other response code returned by the request is considered an error.
|
||||
|
||||
It depends on an authentication service on the backend.
|
||||
|
||||
It works as `ngx_http_auth_request_module` on Nginx
|
||||
```conf
|
||||
location /private/ {
|
||||
auth_request /auth;
|
||||
...
|
||||
}
|
||||
|
||||
location = /auth {
|
||||
proxy_pass ...
|
||||
proxy_pass_request_body off;
|
||||
proxy_set_header Content-Length "";
|
||||
proxy_set_header X-Original-URI $request_uri;
|
||||
}
|
||||
```
|
||||
|
||||
You can also get headers from the authentication request result and inject them into the next request header or params.
|
||||
|
||||
In case you want to get headers from the authentication service and inject them into the next request headers.
|
||||
|
||||
Set the request variable to the given value after the authorization request completes.
|
||||
|
||||
Key is authentication request response header Key. Value is the next Request header Key.
|
||||
|
||||
```yaml
|
||||
headers:
|
||||
## Key Authentication request header key and value is next request header key
|
||||
userId: X-Auth-UserId
|
||||
userCountryId: X-Auth-UserCountryId
|
||||
```
|
||||
The second example, is in case you want to get headers from the authentication request and inject them into the next request parameters.
|
||||
Key is authentication request response header Key. Value is the next Request parameter Key.
|
||||
|
||||
See the example below.
|
||||
|
||||
```yaml
|
||||
# Key Authentication request header key and value is next request parameter key
|
||||
params:
|
||||
userId: userId
|
||||
userCountryId: countryId
|
||||
```
|
||||
Example of JWT middleware
|
||||
```yaml
|
||||
middlewares:
|
||||
#Enables JWT authorization based on the result of a request and continues the request.
|
||||
- name: google-auth
|
||||
# jwt authorization based on the result of backend's response and continue the request when the client is authorized
|
||||
type: jwt
|
||||
# Paths to protect
|
||||
paths:
|
||||
- /protected-access
|
||||
- /example-of-jwt
|
||||
#- /* or wildcard path
|
||||
rule:
|
||||
# This is an example URL
|
||||
url: https://www.googleapis.com/auth/userinfo.email
|
||||
# Required headers, if not present in the request, the proxy will return 403
|
||||
requiredHeaders:
|
||||
- Authorization
|
||||
#Sets the request variable to the given value after the authorization request completes.
|
||||
#
|
||||
# Add header to the next request from AuthRequest header, depending on your requirements
|
||||
# Key is AuthRequest's response header Key, and value is Request's header Key
|
||||
# In case you want to get headers from the authentication service and inject them into the next request header or parameters,
|
||||
#Set the request variable to the given value after completing the authorization request.
|
||||
#
|
||||
# Add header to the next request from AuthRequest header, depending on your requirements
|
||||
# Key is AuthRequest's response header Key, and value is next request header Key
|
||||
# In case you want to get headers from the authentication service and inject them into the next request headers.
|
||||
headers:
|
||||
userId: X-Auth-UserId
|
||||
userCountryId: X-Auth-UserCountryId
|
||||
# In case you want to get headers from the Authentication service and inject them to the next request params.
|
||||
params:
|
||||
userCountryId: countryId
|
||||
```
|
||||
### Access middleware
|
||||
|
||||
Access middleware prevents access to a route or specific route path.
|
||||
|
||||
Example of access middleware
|
||||
```yaml
|
||||
# The server will return 403
|
||||
- name: api-forbidden-paths
|
||||
type: access
|
||||
## prevents access paths
|
||||
paths:
|
||||
- /swagger-ui/*
|
||||
- /v2/swagger-ui/*
|
||||
- /api-docs/*
|
||||
- /internal/*
|
||||
- /actuator/*
|
||||
```
|
||||
### RateLimit middleware
|
||||
|
||||
The RateLimit middleware ensures that services will receive a fair amount of requests, and allows one to define what fair is.
|
||||
|
||||
Example of rateLimit middleware
|
||||
```yaml
|
||||
|
||||
```
|
||||
|
||||
### Apply middleware on the route
|
||||
|
||||
```yaml
|
||||
##### Define routes
|
||||
routes:
|
||||
- name: Basic auth
|
||||
path: /protected
|
||||
rewrite: /
|
||||
destination: 'https://example.com'
|
||||
healthCheck:
|
||||
cors: {}
|
||||
middlewares:
|
||||
# Name of middleware
|
||||
- basic-auth
|
||||
- access
|
||||
```
|
||||
206
docs/quickstart/route.md
Normal file
206
docs/quickstart/route.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
title: Routes
|
||||
layout: default
|
||||
parent: Quickstart
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
|
||||
## Routes
|
||||
|
||||
The Route allows you to match on HTTP traffic and direct it to the backend.
|
||||
|
||||
|
||||
### Create a route
|
||||
|
||||
```yaml
|
||||
##### Define routes
|
||||
routes:
|
||||
# Example of a route | 1
|
||||
- name: Public
|
||||
# host Domain/host based request routing
|
||||
host: "" # Host is optional
|
||||
path: /public
|
||||
## Rewrite a request path
|
||||
# e.g rewrite: /store to /
|
||||
rewrite: /
|
||||
destination: https://example.com
|
||||
#DisableHeaderXForward Disable X-forwarded header.
|
||||
# [X-Forwarded-Host, X-Forwarded-For, Host, Scheme ]
|
||||
# It will not match the backend route, by default, it's disabled
|
||||
disableHeaderXForward: false
|
||||
# Internal health check
|
||||
healthCheck: '' #/internal/health/ready
|
||||
# Route Cors, global cors will be overridden by route
|
||||
cors:
|
||||
# Route Origins Cors, global cors will be overridden by route
|
||||
origins:
|
||||
- https://dev.example.com
|
||||
- http://localhost:3000
|
||||
- https://example.com
|
||||
# Route Cors headers, route will override global cors
|
||||
headers:
|
||||
Access-Control-Allow-Methods: 'GET'
|
||||
Access-Control-Allow-Headers: 'Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id'
|
||||
Access-Control-Allow-Credentials: 'true'
|
||||
Access-Control-Max-Age: 1728000
|
||||
##### Define route middlewares from middlewares names
|
||||
## The name must be unique
|
||||
## List of middleware name
|
||||
middlewares:
|
||||
- api-forbidden-paths
|
||||
- basic-auth
|
||||
```
|
||||
|
||||
### Full example of route
|
||||
|
||||
```yaml
|
||||
## Goma - simple lightweight API Gateway and Reverse Proxy.
|
||||
# Goma Gateway configurations
|
||||
gateway:
|
||||
########## Global settings
|
||||
listenAddr: 0.0.0.0:80
|
||||
# Proxy write timeout
|
||||
writeTimeout: 15
|
||||
# Proxy read timeout
|
||||
readTimeout: 15
|
||||
# Proxy idle timeout
|
||||
idleTimeout: 60
|
||||
# Proxy rate limit, it's In-Memory IP based
|
||||
# Distributed Rate Limiting for Token based across multiple instances is not yet integrated
|
||||
rateLimiter: 0
|
||||
accessLog: "/dev/Stdout"
|
||||
errorLog: "/dev/stderr"
|
||||
## Returns backend route healthcheck errors
|
||||
disableRouteHealthCheckError: false
|
||||
# Disable display routes on start
|
||||
disableDisplayRouteOnStart: false
|
||||
# disableKeepAlive allows enabling and disabling KeepALive server
|
||||
disableKeepAlive: false
|
||||
# interceptErrors intercepts backend errors based on defined the status codes
|
||||
interceptErrors:
|
||||
- 405
|
||||
- 500
|
||||
# - 400
|
||||
# Proxy Global HTTP Cors
|
||||
cors:
|
||||
# Global routes cors for all routes
|
||||
origins:
|
||||
- http://localhost:8080
|
||||
- https://example.com
|
||||
# Global routes cors headers for all routes
|
||||
headers:
|
||||
Access-Control-Allow-Headers: 'Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id'
|
||||
Access-Control-Allow-Credentials: 'true'
|
||||
Access-Control-Max-Age: 1728000
|
||||
##### Define routes
|
||||
routes:
|
||||
# Example of a route | 1
|
||||
- name: Public
|
||||
# host Domain/host based request routing
|
||||
host: "" # Host is optional
|
||||
path: /public
|
||||
## Rewrite a request path
|
||||
# e.g rewrite: /store to /
|
||||
rewrite: /
|
||||
destination: https://example.com
|
||||
#DisableHeaderXForward Disable X-forwarded header.
|
||||
# [X-Forwarded-Host, X-Forwarded-For, Host, Scheme ]
|
||||
# It will not match the backend route, by default, it's disabled
|
||||
disableHeaderXForward: false
|
||||
# Internal health check
|
||||
healthCheck: '' #/internal/health/ready
|
||||
# Route Cors, global cors will be overridden by route
|
||||
cors:
|
||||
# Route Origins Cors, global cors will be overridden by route
|
||||
origins:
|
||||
- https://dev.example.com
|
||||
- http://localhost:3000
|
||||
- https://example.com
|
||||
# Route Cors headers, route will override global cors
|
||||
headers:
|
||||
Access-Control-Allow-Methods: 'GET'
|
||||
Access-Control-Allow-Headers: 'Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id'
|
||||
Access-Control-Allow-Credentials: 'true'
|
||||
Access-Control-Max-Age: 1728000
|
||||
##### Define route middlewares from middlewares names
|
||||
## The name must be unique
|
||||
## List of middleware name
|
||||
middlewares:
|
||||
- api-forbidden-paths
|
||||
- basic-auth
|
||||
# Example of a route | 2
|
||||
- name: Authentication service
|
||||
path: /auth
|
||||
rewrite: /
|
||||
destination: https://example.com
|
||||
healthCheck: /
|
||||
cors: {}
|
||||
middlewares:
|
||||
- api-forbidden-paths
|
||||
# Example of a route | 3
|
||||
- name: Basic auth
|
||||
path: /protected
|
||||
rewrite: /
|
||||
destination: 'http://notification-service:8080'
|
||||
healthCheck:
|
||||
cors: {}
|
||||
middlewares: []
|
||||
|
||||
#Defines proxy middlewares
|
||||
# middleware name must be unique
|
||||
middlewares:
|
||||
# Enable Basic auth authorization based
|
||||
- name: basic-auth
|
||||
# Authentication types | jwt, basic, OAuth
|
||||
type: basic
|
||||
paths:
|
||||
- /user
|
||||
- /admin
|
||||
- /account
|
||||
rule:
|
||||
username: admin
|
||||
password: admin
|
||||
#Enables JWT authorization based on the result of a request and continues the request.
|
||||
- name: google-auth
|
||||
# Authentication types | jwt, basic, OAuth
|
||||
# jwt authorization based on the result of backend's response and continue the request when the client is authorized
|
||||
type: jwt
|
||||
# Paths to protect
|
||||
paths:
|
||||
- /protected-access
|
||||
- /example-of-jwt
|
||||
#- /* or wildcard path
|
||||
rule:
|
||||
# This is an example URL
|
||||
url: https://www.googleapis.com/auth/userinfo.email
|
||||
# Required headers, if not present in the request, the proxy will return 403
|
||||
requiredHeaders:
|
||||
- Authorization
|
||||
#Sets the request variable to the given value after the authorization request completes.
|
||||
#
|
||||
# Add header to the next request from AuthRequest header, depending on your requirements
|
||||
# Key is AuthRequest's response header Key, and value is Request's header Key
|
||||
# In case you want to get headers from the Authentication service and inject them into the next request's headers
|
||||
#Sets the request variable to the given value after the authorization request completes.
|
||||
#
|
||||
# Add header to the next request from AuthRequest header, depending on your requirements
|
||||
# Key is AuthRequest's response header Key, and value is Request's header Key
|
||||
# In case you want to get headers from the authentication service and inject them into the next request headers.
|
||||
headers:
|
||||
userId: X-Auth-UserId
|
||||
userCountryId: X-Auth-UserCountryId
|
||||
# In case you want to get headers from the Authentication service and inject them to the next request params.
|
||||
params:
|
||||
userCountryId: countryId
|
||||
# The server will return 403
|
||||
- name: api-forbidden-paths
|
||||
type: access
|
||||
## prevents access paths
|
||||
paths:
|
||||
- /swagger-ui/*
|
||||
- /v2/swagger-ui/*
|
||||
- /api-docs/*
|
||||
- /internal/*
|
||||
- /actuator/*
|
||||
```
|
||||
Reference in New Issue
Block a user