From 760d21725c947c56e998b9108d35a49e2e6640b1 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 5 Feb 2025 09:29:30 -0500 Subject: [PATCH 1/4] pivoting --- app/_how-tos/nonroot.md | 41 +++++++++++++++++++++ tools/track-docs-changes/config/sources.yml | 4 +- 2 files changed, 43 insertions(+), 2 deletions(-) create mode 100644 app/_how-tos/nonroot.md diff --git a/app/_how-tos/nonroot.md b/app/_how-tos/nonroot.md new file mode 100644 index 000000000..4e3c2d638 --- /dev/null +++ b/app/_how-tos/nonroot.md @@ -0,0 +1,41 @@ +--- +title: Run {{site.base_gateway}} as a non-root user. +content_type: how_to +related_resources: + - text: Enable RBAC + url: /gateway/entities/rbac/#enable-rbac + - text: Create a Super Admin + url: /how-to/create-a-super-admin/ + +products: + - gateway + +works_on: + - on-prem + +tldr: + q: How do you run {{site.base_gateway}} as a non-root user in Linux + a: | + When {{site.base_gateway}} is installed it creates the user group `kong`, users that belong to the `kong` can perform {{site.base_gateway}} actions. Adding your user to that user group will allow you to execute {{site.base_gateway}} commands on the system. + +prereqs: + inline: + - title: Install {{site.base_gateway}} on Ubuntu + include_content: prereqs/install/ubuntu +min_version: + gateway: '3.4' + +tags: + - install +--- + +## 1. Add the existing user to the `kong` group + +```sh + sudo usermod -aG kong your-user +``` + +## 2. Validate + +You can validate by trying to run `kong start` which can only be done by a user or group that has execute access to the Kong directory: + diff --git a/tools/track-docs-changes/config/sources.yml b/tools/track-docs-changes/config/sources.yml index a735fd1f6..91156325d 100644 --- a/tools/track-docs-changes/config/sources.yml +++ b/tools/track-docs-changes/config/sources.yml @@ -166,8 +166,8 @@ app/_how-tos/throttle-apis-with-services-and-consumers.md: app/_how-tos/test-certificate-generation-locally-with-ngrok-and-acme.md: - app/_hub/kong-inc/acme/how-to/_index.md - app/_hub/kong-inc/acme/how-to/_local-testing-development.md - - +app/_how-tos/nonroot.md: + - app/_src/gateway/production/running-kong/kong-user.md ## KIC app/_how-tos/proxy-http-traffic-kic.md: - app/_src/kubernetes-ingress-controller/guides/services/http.md From 339e848823b618fba5b5a85369c32cbc95547e86 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 5 Feb 2025 15:12:54 -0500 Subject: [PATCH 2/4] non-root --- app/_how-tos/install-kgw-securely.md | 4 + app/_how-tos/nonroot.md | 2 +- .../prereqs/install/ee/amazon-linux.md | 27 ++++++ app/_includes/prereqs/install/ee/debian.md | 32 +++++++ app/_includes/prereqs/install/ee/red-hat.md | 27 ++++++ app/_includes/prereqs/install/ee/ubuntu.md | 32 +++++++ app/_includes/prereqs/install/fips/red-hat.md | 33 +++++++ app/_includes/prereqs/install/fips/ubuntu.md | 23 +++++ .../prereqs/install/oss/amazon-linux.md | 27 ++++++ app/_includes/prereqs/install/oss/debian.md | 32 +++++++ app/_includes/prereqs/install/oss/red-hat.md | 27 ++++++ app/_includes/prereqs/install/oss/ubuntu.md | 32 +++++++ app/_landing_pages/install.yaml | 10 -- app/gateway/fips.md | 19 ++++ app/gateway/installation.md | 95 +++++++++++++++++++ 15 files changed, 411 insertions(+), 11 deletions(-) create mode 100644 app/_includes/prereqs/install/ee/amazon-linux.md create mode 100644 app/_includes/prereqs/install/ee/debian.md create mode 100644 app/_includes/prereqs/install/ee/red-hat.md create mode 100644 app/_includes/prereqs/install/ee/ubuntu.md create mode 100644 app/_includes/prereqs/install/fips/red-hat.md create mode 100644 app/_includes/prereqs/install/fips/ubuntu.md create mode 100644 app/_includes/prereqs/install/oss/amazon-linux.md create mode 100644 app/_includes/prereqs/install/oss/debian.md create mode 100644 app/_includes/prereqs/install/oss/red-hat.md create mode 100644 app/_includes/prereqs/install/oss/ubuntu.md delete mode 100644 app/_landing_pages/install.yaml create mode 100644 app/gateway/fips.md create mode 100644 app/gateway/installation.md diff --git a/app/_how-tos/install-kgw-securely.md b/app/_how-tos/install-kgw-securely.md index 1f2974cde..68059dbc7 100644 --- a/app/_how-tos/install-kgw-securely.md +++ b/app/_how-tos/install-kgw-securely.md @@ -42,7 +42,11 @@ tools: prereqs: inline: - title: Install {{site.base_gateway}} +<<<<<<< HEAD include_content: prereqs/install/gateway/red-hat +======= + include_content: prereqs/install/ee/red-hat +>>>>>>> dc5052b9 (non-root) cleanup: inline: diff --git a/app/_how-tos/nonroot.md b/app/_how-tos/nonroot.md index 4e3c2d638..c45bd2140 100644 --- a/app/_how-tos/nonroot.md +++ b/app/_how-tos/nonroot.md @@ -21,7 +21,7 @@ tldr: prereqs: inline: - title: Install {{site.base_gateway}} on Ubuntu - include_content: prereqs/install/ubuntu + include_content: prereqs/install/ee/ubuntu min_version: gateway: '3.4' diff --git a/app/_includes/prereqs/install/ee/amazon-linux.md b/app/_includes/prereqs/install/ee/amazon-linux.md new file mode 100644 index 000000000..1f4eb6875 --- /dev/null +++ b/app/_includes/prereqs/install/ee/amazon-linux.md @@ -0,0 +1,27 @@ +{% navtabs %} +{% navtab "Manually installation" %} +1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-enterprise-edition-3.9.0.1.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/amzn/%{amzn}/%{_arch}/kong-enterprise-edition-3.9.0.1.aws.%{_arch}.rpm) + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-3.9.0.1.rpm + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=amzn&codename=$(rpm --eval '%{amzn}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo > /dev/null + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-3.9.0.1 + ``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/ee/debian.md b/app/_includes/prereqs/install/ee/debian.md new file mode 100644 index 000000000..1d2dcc96f --- /dev/null +++ b/app/_includes/prereqs/install/ee/debian.md @@ -0,0 +1,32 @@ +{% navtabs %} +{% navtab "Manual installation" %} +1. Download {{site.base_gateway}}: +```sh +curl -Lo kong-enterprise-edition-3.9.0.1.deb "https://packages.konghq.com/public/gateway-39/deb/debian/pool/bullseye/main/k/ko/kong-enterprise-edition_3.9.0.1/kong-enterprise-edition_3.9.0.1_$(dpkg --print-architecture).deb" +``` + +2. Install {{site.base_gateway}}: + ``` + sudo apt install -y ./kong-enterprise-edition-3.9.0.1.deb + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: +```sh +curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg > /dev/null +``` +``` +curl -1sLf "https://packages.konghq.com/public/gateway-39/config.deb.txt?distro=debian&codename=$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/kong-gateway-39.list > /dev/null +``` +2. Update the package manager: + + ```sh + sudo apt update + ``` + +3. Install {{site.base_gateway}}: +``` +sudo apt install -y kong-enterprise-edition=3.9.0.1 +``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/ee/red-hat.md b/app/_includes/prereqs/install/ee/red-hat.md new file mode 100644 index 000000000..d990e1dac --- /dev/null +++ b/app/_includes/prereqs/install/ee/red-hat.md @@ -0,0 +1,27 @@ +{% navtabs %} +{% navtab "Manual Installation" %} +1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-enterprise-edition-3.9.0.1.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/el/%{rhel}/%{_arch}/kong-enterprise-edition-3.9.0.1.el%{rhel}.%{_arch}.rpm) + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-3.9.0.1.rpm + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=el&codename=$(rpm --eval '%{rhel}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-3.9.0.1 + ``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/ee/ubuntu.md b/app/_includes/prereqs/install/ee/ubuntu.md new file mode 100644 index 000000000..e8e33de37 --- /dev/null +++ b/app/_includes/prereqs/install/ee/ubuntu.md @@ -0,0 +1,32 @@ +{% navtabs %} +{% navtab "Manual installation" %} +1. Download {{site.base_gateway}}: +```sh +curl -Lo kong-enterprise-edition-3.9.0.1.deb "https://packages.konghq.com/public/gateway-39/deb/ubuntu/pool/noble/main/k/ko/kong-enterprise-edition_3.9.0.1/kong-enterprise-edition_3.9.0.1_$(dpkg --print-architecture).deb" +``` + +2. Install {{site.base_gateway}}: + ``` + sudo apt install -y ./kong-enterprise-edition-3.9.0.1.deb + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: +```sh +curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg > /dev/null +``` +``` +curl -1sLf "https://packages.konghq.com/public/gateway-39/config.deb.txt?distro=debian&codename=$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/kong-gateway-39.list > /dev/null +``` +2. Update the package manager: + + ```sh + sudo apt update + ``` + +3. Install {{site.base_gateway}}: +``` +sudo apt install -y kong-enterprise-edition=3.9.0.1 +``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/fips/red-hat.md b/app/_includes/prereqs/install/fips/red-hat.md new file mode 100644 index 000000000..6800d7f92 --- /dev/null +++ b/app/_includes/prereqs/install/fips/red-hat.md @@ -0,0 +1,33 @@ +{% navtabs %} +{% navtab "Manual Installation" %} +1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-enterprise-edition-fips-3.9.0.1.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/el/%{rhel}/x86_64/kong-enterprise-edition-fips-3.9.0.1.el%{rhel}.x86_64.rpm) + ``` + +2. Install {{site.base_gateway}}: + ``` + yum install kong-enterprise-edition-fips-3.9.1.0 + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=el&codename=$(rpm --eval '%{rhel}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' + ``` + +2. Install {{site.base_gateway}}: + ``` + yum install kong-enterprise-edition-fips-3.9.1.0 + ``` +{% endnavtab %} +{% endnavtabs %} + +3. Enable FIPS + +```sh +export KONG_FIPS=on && kong reload +``` \ No newline at end of file diff --git a/app/_includes/prereqs/install/fips/ubuntu.md b/app/_includes/prereqs/install/fips/ubuntu.md new file mode 100644 index 000000000..b000c8d57 --- /dev/null +++ b/app/_includes/prereqs/install/fips/ubuntu.md @@ -0,0 +1,23 @@ +1. Set up the package repository: +```sh +curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor >> /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg +``` +``` +curl -1sLf "https://packages.konghq.com/public/gateway-38/config.deb.txt?distro=ubuntu&codename=$(lsb_release -sc)" > /etc/apt/sources.list.d/kong-gateway-39.list +``` +2. Update the package manager: + + ```sh + sudo apt update + ``` + +3. Install {{site.base_gateway}}: +``` +apt install -y kong-enterprise-edition-fips=3.9.1.0 +``` + +4. Enable FIPS + +```sh +export KONG_FIPS=on && kong reload +``` \ No newline at end of file diff --git a/app/_includes/prereqs/install/oss/amazon-linux.md b/app/_includes/prereqs/install/oss/amazon-linux.md new file mode 100644 index 000000000..9f16e24b2 --- /dev/null +++ b/app/_includes/prereqs/install/oss/amazon-linux.md @@ -0,0 +1,27 @@ +{% navtabs %} +{% navtab "Manually installation" %} +1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-3.9.0.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/amzn/%{amzn}/%{_arch}/kong-3.9.0.aws.%{_arch}.rpm) + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-3.9.0.rpm + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=amzn&codename=$(rpm --eval '%{amzn}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo > /dev/null + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-3.9.0 + ``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/oss/debian.md b/app/_includes/prereqs/install/oss/debian.md new file mode 100644 index 000000000..1d2dcc96f --- /dev/null +++ b/app/_includes/prereqs/install/oss/debian.md @@ -0,0 +1,32 @@ +{% navtabs %} +{% navtab "Manual installation" %} +1. Download {{site.base_gateway}}: +```sh +curl -Lo kong-enterprise-edition-3.9.0.1.deb "https://packages.konghq.com/public/gateway-39/deb/debian/pool/bullseye/main/k/ko/kong-enterprise-edition_3.9.0.1/kong-enterprise-edition_3.9.0.1_$(dpkg --print-architecture).deb" +``` + +2. Install {{site.base_gateway}}: + ``` + sudo apt install -y ./kong-enterprise-edition-3.9.0.1.deb + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: +```sh +curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg > /dev/null +``` +``` +curl -1sLf "https://packages.konghq.com/public/gateway-39/config.deb.txt?distro=debian&codename=$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/kong-gateway-39.list > /dev/null +``` +2. Update the package manager: + + ```sh + sudo apt update + ``` + +3. Install {{site.base_gateway}}: +``` +sudo apt install -y kong-enterprise-edition=3.9.0.1 +``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/oss/red-hat.md b/app/_includes/prereqs/install/oss/red-hat.md new file mode 100644 index 000000000..7bb44046e --- /dev/null +++ b/app/_includes/prereqs/install/oss/red-hat.md @@ -0,0 +1,27 @@ +{% navtabs %} +{% navtab "Manual Installation" %} +1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-3.9.0.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/el/%{rhel}/%{_arch}/kong-3.9.0.el%{rhel}.%{_arch}.rpm) + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-3.9.0.rpm + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=el&codename=$(rpm --eval '%{rhel}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' + ``` + +2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-3.9.0 + ``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/oss/ubuntu.md b/app/_includes/prereqs/install/oss/ubuntu.md new file mode 100644 index 000000000..f03e6fdfd --- /dev/null +++ b/app/_includes/prereqs/install/oss/ubuntu.md @@ -0,0 +1,32 @@ +{% navtabs %} +{% navtab "Manual installation" %} +1. Download {{site.base_gateway}}: +```sh +curl -Lo kong-3.9.0.deb "https://packages.konghq.com/public/gateway-39/deb/ubuntu/pool/noble/main/k/ko/kong_3.9.0/kong_3.9.0_$(dpkg --print-architecture).deb" +``` + +2. Install {{site.base_gateway}}: + ``` + sudo apt install -y ./kong-3.9.0.deb + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: +```sh +curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg > /dev/null +``` +``` +curl -1sLf "https://packages.konghq.com/public/gateway-39/config.deb.txt?distro=ubuntu&codename=noble" | sudo tee /etc/apt/sources.list.d/kong-gateway-39.list > /dev/null +``` +2. Update the package manager: + + ```sh + sudo apt update + ``` + +3. Install {{site.base_gateway}}: +``` +sudo apt-get install -y kong=3.9.0 +``` +{% endnavtab %} +{% endnavtabs %} \ No newline at end of file diff --git a/app/_landing_pages/install.yaml b/app/_landing_pages/install.yaml deleted file mode 100644 index 5d5454218..000000000 --- a/app/_landing_pages/install.yaml +++ /dev/null @@ -1,10 +0,0 @@ -metadata: - title: Installation options - content_type: landing_page - description: Installation options - -rows: - - header: - type: h1 - text: "@todo" - diff --git a/app/gateway/fips.md b/app/gateway/fips.md new file mode 100644 index 000000000..69f17fad6 --- /dev/null +++ b/app/gateway/fips.md @@ -0,0 +1,19 @@ +--- +title: "FIPS PAGE" + +description: | + {{site.base_gate}} installation reference +content_type: reference +layout: reference +products: + - gateway + +related_resources: + - text: "Managing {{site.base_gateway}} configuration" + url: /gateway/manage-kong-conf/ + +works_on: + - on-prem +--- + +@TODO \ No newline at end of file diff --git a/app/gateway/installation.md b/app/gateway/installation.md new file mode 100644 index 000000000..6fec94f7e --- /dev/null +++ b/app/gateway/installation.md @@ -0,0 +1,95 @@ +--- +title: "{{site.base_gateway}} Installation Reference" + +description: | + {{site.base_gate}} installation reference +content_type: reference +layout: reference +products: + - gateway + +related_resources: + - text: "Managing {{site.base_gateway}} configuration" + url: /gateway/manage-kong-conf/ + +works_on: + - on-prem +--- + + +## Linux +### Enterprise +{% navtabs %} +{% navtab "Debian" %} +{% include prereqs/install/ee/debian.md %} +{% endnavtab %} +{% navtab "Ubuntu" %} +{% include prereqs/install/ee/ubuntu.md %} +{% endnavtab %} +{% navtab "Amazon Linux" %} +{% include prereqs/install/ee/amazon-linux.md %} +{% endnavtab %} +{% navtab "Red Hat" %} +{% include prereqs/install/ee/red-hat.md %} +{% endnavtab %} +{% endnavtabs %} +### Open Source + +{% navtabs %} +{% navtab "Debian" %} +{% include prereqs/install/oss/debian.md %} +{% endnavtab %} +{% navtab "Ubuntu" %} +{% include prereqs/install/oss/ubuntu.md %} +{% endnavtab %} +{% navtab "Amazon Linux" %} +{% include prereqs/install/oss/amazon-linux.md %} +{% endnavtab %} +{% navtab "Red Hat" %} +{% include prereqs/install/oss/red-hat.md %} +{% endnavtab %} +{% endnavtabs %} + + +### FIPS install + +{{site.base_gateway}} provides a FIPS 140-2 compliant package for Ubuntu 20.04 , Ubuntu 22.04 , Red Hat Enterprise 9 , and Red Hat Enterprise 8 . This package provides compliance for the core {{site.base_gateway}} product and all out of the box plugins. For more information see the [FIPS reference page](/gateway/fips/) + + +{% navtabs %} +{% navtab "Ubuntu" %} +{% include prereqs/install/fips/ubuntu.md %} +{% endnavtab %} +{% navtab "Red Hat" %} +{% include prereqs/install/fips/red-hat.md %} +{% endnavtab %} +{% endnavtabs %} + +## Running {{site.base_gateway}} as a non-root user + +When {{site.base_gateway}} is installed, the installation process creates the user group `kong`, users that belong to the `kong` can perform {{site.base_gateway}} actions. Adding your user to that user group will allow you to execute {{site.base_gateway}} commands on the system. + + + +You can check the permissions and ownership of the {{site.base_gateway}} in Linux like this: + +`ls -l /usr/local/kong` + +Which will return a list of subdirectories that contain a prefix like this: +`drwxrwxr-x 2 kong kong` + +The two `kong` values mean that the directory is owned by the user `kong` and the group `kong`. + +In Linux to make an existing user part of the Kong group you can run this command: + +`usermod -aG kong $USER` + +To view existing groups associated with the user: + +`groups $USER`. + + +### Nginx + +In {{site.base_gateway}} the Nginx master process runs at the `root` level so that Nginx can execute actions even if {{site.base_gateway}} is running as a non-root user. This is important when building containers. + From 7507fce48991cd4fcd3bab274b71b28c74f0bffd Mon Sep 17 00:00:00 2001 From: Angel Date: Tue, 18 Feb 2025 12:00:41 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- app/_how-tos/nonroot.md | 2 +- app/_includes/prereqs/install/fips/red-hat.md | 4 ++-- app/_includes/prereqs/install/fips/ubuntu.md | 1 - .../prereqs/install/oss/amazon-linux.md | 2 +- app/_includes/prereqs/install/oss/red-hat.md | 2 +- app/gateway/installation.md | 19 ++++++++++++------- 6 files changed, 17 insertions(+), 13 deletions(-) diff --git a/app/_how-tos/nonroot.md b/app/_how-tos/nonroot.md index c45bd2140..88f8a7546 100644 --- a/app/_how-tos/nonroot.md +++ b/app/_how-tos/nonroot.md @@ -32,7 +32,7 @@ tags: ## 1. Add the existing user to the `kong` group ```sh - sudo usermod -aG kong your-user +sudo usermod -aG kong your-user ``` ## 2. Validate diff --git a/app/_includes/prereqs/install/fips/red-hat.md b/app/_includes/prereqs/install/fips/red-hat.md index 6800d7f92..f7aede36b 100644 --- a/app/_includes/prereqs/install/fips/red-hat.md +++ b/app/_includes/prereqs/install/fips/red-hat.md @@ -1,5 +1,5 @@ {% navtabs %} -{% navtab "Manual Installation" %} +{% navtab "Manual installation" %} 1. Download {{site.base_gateway}}: ```sh curl -Lo kong-enterprise-edition-fips-3.9.0.1.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/el/%{rhel}/x86_64/kong-enterprise-edition-fips-3.9.0.1.el%{rhel}.x86_64.rpm) @@ -26,7 +26,7 @@ {% endnavtab %} {% endnavtabs %} -3. Enable FIPS +3. Enable FIPS: ```sh export KONG_FIPS=on && kong reload diff --git a/app/_includes/prereqs/install/fips/ubuntu.md b/app/_includes/prereqs/install/fips/ubuntu.md index b000c8d57..5b1722973 100644 --- a/app/_includes/prereqs/install/fips/ubuntu.md +++ b/app/_includes/prereqs/install/fips/ubuntu.md @@ -17,7 +17,6 @@ apt install -y kong-enterprise-edition-fips=3.9.1.0 ``` 4. Enable FIPS - ```sh export KONG_FIPS=on && kong reload ``` \ No newline at end of file diff --git a/app/_includes/prereqs/install/oss/amazon-linux.md b/app/_includes/prereqs/install/oss/amazon-linux.md index 9f16e24b2..9c409ac38 100644 --- a/app/_includes/prereqs/install/oss/amazon-linux.md +++ b/app/_includes/prereqs/install/oss/amazon-linux.md @@ -1,5 +1,5 @@ {% navtabs %} -{% navtab "Manually installation" %} +{% navtab "Manual installation" %} 1. Download {{site.base_gateway}}: ```sh curl -Lo kong-3.9.0.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/amzn/%{amzn}/%{_arch}/kong-3.9.0.aws.%{_arch}.rpm) diff --git a/app/_includes/prereqs/install/oss/red-hat.md b/app/_includes/prereqs/install/oss/red-hat.md index 7bb44046e..cafcdb378 100644 --- a/app/_includes/prereqs/install/oss/red-hat.md +++ b/app/_includes/prereqs/install/oss/red-hat.md @@ -1,5 +1,5 @@ {% navtabs %} -{% navtab "Manual Installation" %} +{% navtab "Manual installation" %} 1. Download {{site.base_gateway}}: ```sh curl -Lo kong-3.9.0.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/el/%{rhel}/%{_arch}/kong-3.9.0.el%{rhel}.%{_arch}.rpm) diff --git a/app/gateway/installation.md b/app/gateway/installation.md index 6fec94f7e..c7e147376 100644 --- a/app/gateway/installation.md +++ b/app/gateway/installation.md @@ -1,5 +1,5 @@ --- -title: "{{site.base_gateway}} Installation Reference" +title: "Install {{site.base_gateway}} on Linux" description: | {{site.base_gate}} installation reference @@ -53,7 +53,7 @@ works_on: ### FIPS install -{{site.base_gateway}} provides a FIPS 140-2 compliant package for Ubuntu 20.04 , Ubuntu 22.04 , Red Hat Enterprise 9 , and Red Hat Enterprise 8 . This package provides compliance for the core {{site.base_gateway}} product and all out of the box plugins. For more information see the [FIPS reference page](/gateway/fips/) +{{site.base_gateway}} provides a FIPS 140-2 compliant package for Ubuntu 20.04, Ubuntu 22.04, Red Hat Enterprise 9, and Red Hat Enterprise 8. This package provides compliance for the core {{site.base_gateway}} product and all out of the box plugins. For more information, see the [FIPS reference page](/gateway/fips/). {% navtabs %} @@ -67,7 +67,12 @@ works_on: ## Running {{site.base_gateway}} as a non-root user -When {{site.base_gateway}} is installed, the installation process creates the user group `kong`, users that belong to the `kong` can perform {{site.base_gateway}} actions. Adding your user to that user group will allow you to execute {{site.base_gateway}} commands on the system. +When {{site.base_gateway}} is installed, the installation process creates the user group `kong`. Users that belong to the `kong` group can perform {{site.base_gateway}} actions. Adding your user to that user group will allow you to execute {{site.base_gateway}} commands on the system. + +{:.warning} +> **Warning:** The Nginx master process needs to run as `root` for Nginx to execute certain actions (for example, to listen on the privileged port 80). +>

+> Although running Kong as the `kong` user and group does provide more security, we advise that a system and network administration evaluation be performed before making this decision. Otherwise, Kong nodes might become unavailable due to insufficient permissions to execute privileged system calls in the operating system. @@ -80,16 +85,16 @@ Which will return a list of subdirectories that contain a prefix like this: The two `kong` values mean that the directory is owned by the user `kong` and the group `kong`. -In Linux to make an existing user part of the Kong group you can run this command: +To make an existing user part of the `kong` group, you can run this command: `usermod -aG kong $USER` -To view existing groups associated with the user: +To view existing groups associated with the user, run: -`groups $USER`. +`groups $USER` ### Nginx -In {{site.base_gateway}} the Nginx master process runs at the `root` level so that Nginx can execute actions even if {{site.base_gateway}} is running as a non-root user. This is important when building containers. +In {{site.base_gateway}}, the Nginx master process runs at the `root` level so that Nginx can execute actions even if {{site.base_gateway}} is running as a non-root user. This is important when building containers. From e8e629bfe009d5cbe28a216448322d2b443899f3 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 19 Feb 2025 14:48:55 -0500 Subject: [PATCH 4/4] pause point --- app/_how-tos/install-kgw-amazon-linux.md | 67 +++++++++++++++++ app/_how-tos/install-kgw-debian.md | 73 ++++++++++++++++++ app/_how-tos/install-kgw-red-hat-fips.md | 68 +++++++++++++++++ app/_how-tos/install-kgw-red-hat.md | 67 +++++++++++++++++ app/_how-tos/install-kgw-securely.md | 4 - app/_how-tos/install-kgw-ubuntu-fips.md | 60 +++++++++++++++ app/_how-tos/install-kgw-ubuntu.md | 74 +++++++++++++++++++ app/_how-tos/nonroot.md | 2 +- app/_includes/how-tos/steps/datastore.md | 54 ++++++++++++++ .../prereqs/install/ee/amazon-linux.md | 27 ------- app/_includes/prereqs/install/ee/debian.md | 32 -------- app/_includes/prereqs/install/ee/red-hat.md | 27 ------- app/_includes/prereqs/install/ee/ubuntu.md | 32 -------- app/_includes/prereqs/install/fips/ubuntu.md | 6 +- .../gateway/datastore-env-variables.md | 10 +++ .../prereqs/install/gateway/nonroot.md | 33 +++++++++ app/_landing_pages/gateway/installation.yaml | 33 +++++++++ app/gateway/installation.md | 66 +---------------- 18 files changed, 546 insertions(+), 189 deletions(-) create mode 100644 app/_how-tos/install-kgw-amazon-linux.md create mode 100644 app/_how-tos/install-kgw-debian.md create mode 100644 app/_how-tos/install-kgw-red-hat-fips.md create mode 100644 app/_how-tos/install-kgw-red-hat.md create mode 100644 app/_how-tos/install-kgw-ubuntu-fips.md create mode 100644 app/_how-tos/install-kgw-ubuntu.md create mode 100644 app/_includes/how-tos/steps/datastore.md delete mode 100644 app/_includes/prereqs/install/ee/amazon-linux.md delete mode 100644 app/_includes/prereqs/install/ee/debian.md delete mode 100644 app/_includes/prereqs/install/ee/red-hat.md delete mode 100644 app/_includes/prereqs/install/ee/ubuntu.md create mode 100644 app/_includes/prereqs/install/gateway/datastore-env-variables.md create mode 100644 app/_includes/prereqs/install/gateway/nonroot.md create mode 100644 app/_landing_pages/gateway/installation.yaml diff --git a/app/_how-tos/install-kgw-amazon-linux.md b/app/_how-tos/install-kgw-amazon-linux.md new file mode 100644 index 000000000..57c346845 --- /dev/null +++ b/app/_how-tos/install-kgw-amazon-linux.md @@ -0,0 +1,67 @@ +--- +title: Install {{site.base_gateway}} on Amazon Linux +content_type: how_to +products: + - gateway + +works_on: + - on-prem + +min_version: + gateway: '3.4' + + +tags: + - rate-limiting + +tldr: + q: How do I install {{site.base_gateway}} on Amazon Linux + a: Download the {{site.base_gateway}} package and install it using your package manager. Then configure the database. + +tools: + - deck + +prereqs: + skip_product: true + inline: + - title: Install PostgreSQL + content: | + [Install PostgreSQL](https://www.postgresql.org/download/) + - title: Configure environment variables + include_content: prereqs/install/gateway/datastore-env-variables + icon_url: /assets/icons/file.svg +--- + +{% navtabs %} +{% navtab "Manually installation" %} +## 1. Download the {{site.base_gateway}} RPM package + + ```sh + curl -Lo kong-enterprise-edition-{{page.latest_release.ee_version}}.rpm $(rpm --eval https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/rpm/amzn/%{amzn}/%{_arch}/kong-enterprise-edition-{{page.latest_release.ee_version}}.aws.%{_arch}.rpm) + ``` + +## 2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-{{page.latest_release.ee_version}}.rpm + ``` + +{% endnavtab %} +{% navtab "Package manager" %} +## 1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/config.rpm.txt?distro=amzn&codename=$(rpm --eval '%{amzn}')" | sudo tee /etc/yum.repos.d/kong-gateway-{{page.latest_release.major_minor_version}}.repo > /dev/null + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-{{page.latest_release.major_minor_version}}' + ``` + +## 2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-{{page.latest_release.ee_version}} + ``` +{% endnavtab %} +{% endnavtabs %} + +## Configure the Datastore + +{% include how-tos/steps/datastore.md %} \ No newline at end of file diff --git a/app/_how-tos/install-kgw-debian.md b/app/_how-tos/install-kgw-debian.md new file mode 100644 index 000000000..4376d6ba1 --- /dev/null +++ b/app/_how-tos/install-kgw-debian.md @@ -0,0 +1,73 @@ +--- +title: Install {{site.base_gateway}} on Debian +content_type: how_to +products: + - gateway + +works_on: + - on-prem + +min_version: + gateway: '3.4' + + +tags: + - rate-limiting + +tldr: + q: How do I install {{site.base_gateway}} on Debian? + a: Download the {{site.base_gateway}} package and install it using your package manager. Then configure the database. + +tools: + - deck + +prereqs: + skip_product: true + inline: + - title: Install PostgreSQL + content: | + [Install PostgreSQL](https://www.postgresql.org/download/) + - title: Configure environment variables + include_content: prereqs/install/gateway/datastore-env-variables + icon_url: /assets/icons/file.svg +--- +{% navtabs %} +{% navtab "Manual installation" %} +## 1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-enterprise-edition-{{page.latest_release.ee_version}}.deb "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/deb/debian/pool/bullseye/main/k/ko/kong-enterprise-edition_{{page.latest_release.ee_version}}/kong-enterprise-edition_{{page.latest_release.ee_version}}_$(dpkg --print-architecture).deb" + ``` + +## 2. Install {{site.base_gateway}}: + ``` + sudo apt install -y ./kong-enterprise-edition-{{page.latest_release.ee_version}}.deb + ``` + +{% endnavtab %} +{% navtab "Package manager" %} +## 1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-{{page.latest_release.major_minor_version}}-archive-keyring.gpg > /dev/null + ``` + + ``` + curl -1sLf "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/config.deb.txt?distro=debian&codename=$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/kong-gateway-{{page.latest_release.major_minor_version}}.list > /dev/null + ``` + +## 2. Update the package manager: + + ```sh + sudo apt update + ``` + +## 3. Install {{site.base_gateway}}: + ``` + sudo apt install -y kong-enterprise-edition={{page.latest_release.ee_version}} + ``` + +{% endnavtab %} +{% endnavtabs %} + +## Configure the Datastore + +{% include how-tos/steps/datastore.md %} \ No newline at end of file diff --git a/app/_how-tos/install-kgw-red-hat-fips.md b/app/_how-tos/install-kgw-red-hat-fips.md new file mode 100644 index 000000000..7d6516ec6 --- /dev/null +++ b/app/_how-tos/install-kgw-red-hat-fips.md @@ -0,0 +1,68 @@ +--- +title: Install {{site.base_gateway}} FIPS on Red Hat +content_type: how_to +products: + - gateway +works_on: + - on-prem + +min_version: + gateway: '3.4' +tags: + - rate-limiting + +tldr: + q: How do I install the {{site.base_gateway}} FIPS package on Red Hat? + a: Download the {{site.base_gateway}} package and install it using your package manager. Then configure the database. + +tools: + - deck + +prereqs: + skip_product: true + inline: + - title: Install PostgreSQL + content: | + [Install PostgreSQL](https://www.postgresql.org/download/) + - title: Configure environment variables + include_content: prereqs/install/gateway/datastore-env-variables + icon_url: /assets/icons/file.svg +--- + +{% navtabs %} +{% navtab "Manual installation" %} +1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-enterprise-edition-fips-3.9.0.1.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/el/%{rhel}/x86_64/kong-enterprise-edition-fips-3.9.0.1.el%{rhel}.x86_64.rpm) + ``` + +2. Install {{site.base_gateway}}: + ``` + yum install kong-enterprise-edition-fips-3.9.1.0 + ``` +{% endnavtab %} +{% navtab "Package manager" %} +1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=el&codename=$(rpm --eval '%{rhel}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' + ``` + +2. Install {{site.base_gateway}}: + ``` + yum install kong-enterprise-edition-fips-3.9.1.0 + ``` +{% endnavtab %} +{% endnavtabs %} + +3. Enable FIPS: + +```sh +export KONG_FIPS=on && kong reload +``` + +## Configure the Datastore + +{% include how-tos/steps/datastore.md %} \ No newline at end of file diff --git a/app/_how-tos/install-kgw-red-hat.md b/app/_how-tos/install-kgw-red-hat.md new file mode 100644 index 000000000..e4ae0eab3 --- /dev/null +++ b/app/_how-tos/install-kgw-red-hat.md @@ -0,0 +1,67 @@ +--- +title: Install {{site.base_gateway}} on Red Hat +content_type: how_to +products: + - gateway + +works_on: + - on-prem + +min_version: + gateway: '3.4' + + +tags: + - rate-limiting + +tldr: + q: How do I install {{site.base_gateway}} on Red Hat? + a: Download the {{site.base_gateway}} package and install it using your package manager. Then configure the database. + +tools: + - deck + +prereqs: + skip_product: true + inline: + - title: Install PostgreSQL + content: | + [Install PostgreSQL](https://www.postgresql.org/download/) + - title: Configure environment variables + include_content: prereqs/install/gateway/datastore-env-variables + icon_url: /assets/icons/file.svg +--- + +{% navtabs %} +{% navtab "Manual Installation" %} +## 1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-enterprise-edition-{{page.latest_release.ee_version}}.rpm $(rpm --eval https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/rpm/el/%{rhel}/%{_arch}/kong-enterprise-edition-{{page.latest_release.ee_version}}.el%{rhel}.%{_arch}.rpm) + ``` + +## 2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-{{page.latest_release.ee_version}}.rpm + ``` + +{% endnavtab %} +{% navtab "Package manager" %} +## 1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/config.rpm.txt?distro=el&codename=$(rpm --eval '%{rhel}')" | sudo tee /etc/yum.repos.d/kong-gateway-{{page.latest_release.major_minor_version}}.repo + ``` + ``` + sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-{{page.latest_release.major_minor_version}}' + ``` + +## 2. Install {{site.base_gateway}}: + ``` + sudo yum install -y kong-enterprise-edition-{{page.latest_release.ee_version}} + ``` + +{% endnavtab %} +{% endnavtabs %} + +## Configure the Datastore + +{% include how-tos/steps/datastore.md %} \ No newline at end of file diff --git a/app/_how-tos/install-kgw-securely.md b/app/_how-tos/install-kgw-securely.md index 68059dbc7..1f2974cde 100644 --- a/app/_how-tos/install-kgw-securely.md +++ b/app/_how-tos/install-kgw-securely.md @@ -42,11 +42,7 @@ tools: prereqs: inline: - title: Install {{site.base_gateway}} -<<<<<<< HEAD include_content: prereqs/install/gateway/red-hat -======= - include_content: prereqs/install/ee/red-hat ->>>>>>> dc5052b9 (non-root) cleanup: inline: diff --git a/app/_how-tos/install-kgw-ubuntu-fips.md b/app/_how-tos/install-kgw-ubuntu-fips.md new file mode 100644 index 000000000..7d351b171 --- /dev/null +++ b/app/_how-tos/install-kgw-ubuntu-fips.md @@ -0,0 +1,60 @@ +--- +title: Install {{site.base_gateway}} FIPS package on Ubuntu +content_type: how_to +products: + - gateway + +works_on: + - on-prem + +min_version: + gateway: '3.4' + +tags: + - rate-limiting + +tldr: + q: How do I install the {{site.base_gateway}} FIPS package on Ubuntu? + a: Download the {{site.base_gateway}} package and install it using your package manager. Then configure the database. + +tools: + - deck + +prereqs: + skip_product: true + inline: + - title: Install PostgreSQL + content: | + [Install PostgreSQL](https://www.postgresql.org/download/) + - title: Configure environment variables + include_content: prereqs/install/gateway/datastore-env-variables + icon_url: /assets/icons/file.svg +--- + + +## 1. Set up the package repository: +```sh +curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor >> /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg +``` +``` +curl -1sLf "https://packages.konghq.com/public/gateway-38/config.deb.txt?distro=ubuntu&codename=$(lsb_release -sc)" > /etc/apt/sources.list.d/kong-gateway-39.list +``` +## 2. Update the package manager: + + ```sh + sudo apt update + ``` + +## 3. Install {{site.base_gateway}}: +``` +apt install -y kong-enterprise-edition-fips=3.9.1.0 +``` + +## 4. Enable FIPS +```sh +export KONG_FIPS=on && kong reload +``` + +## Configure the Datastore + +{% include how-tos/steps/datastore.md %} \ No newline at end of file diff --git a/app/_how-tos/install-kgw-ubuntu.md b/app/_how-tos/install-kgw-ubuntu.md new file mode 100644 index 000000000..35f1ebe1b --- /dev/null +++ b/app/_how-tos/install-kgw-ubuntu.md @@ -0,0 +1,74 @@ +--- +title: Install {{site.base_gateway}} on Ubuntu +content_type: how_to +products: + - gateway + +works_on: + - on-prem + +min_version: + gateway: '3.4' + +tags: + - rate-limiting + +tldr: + q: How do I install {{site.base_gateway}} on Ubuntu? + a: Download the {{site.base_gateway}} package and install it using your package manager. Then configure the database. + +tools: + - deck + +prereqs: + skip_product: true + inline: + - title: Install PostgreSQL + content: | + [Install PostgreSQL](https://www.postgresql.org/download/) + - title: Configure environment variables + include_content: prereqs/install/gateway/datastore-env-variables + icon_url: /assets/icons/file.svg +--- + +{% navtabs %} +{% navtab "Manual installation" %} +## 1. Download {{site.base_gateway}}: + ```sh + curl -Lo kong-enterprise-edition-{{page.latest_release.ee_version}}.deb "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/deb/ubuntu/pool/noble/main/k/ko/kong-enterprise-edition_{{page.latest_release.ee_version}}/kong-enterprise-edition_{{page.latest_release.ee_version}}_$(dpkg --print-architecture).deb" + ``` + +## 2. Install {{site.base_gateway}}: + ``` + sudo apt install -y ./kong-enterprise-edition-{{page.latest_release.ee_version}}.deb + ``` + +{% endnavtab %} +{% navtab "Package manager" %} +## 1. Set up the package repository: + ```sh + curl -1sLf "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-{{page.latest_release.major_minor_version}}-archive-keyring.gpg > /dev/null + ``` + + ``` + curl -1sLf "https://packages.konghq.com/public/gateway-{{page.latest_release.major_minor_version}}/config.deb.txt?distro=debian&codename=$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/kong-gateway-{{page.latest_release.major_minor_version}}.list > /dev/null + ``` + +## 2. Update the package manager: + + ```sh + sudo apt update + ``` + +## 3. Install {{site.base_gateway}}: + ``` + sudo apt install -y kong-enterprise-edition={{page.latest_release.ee_version}} + ``` + +{% endnavtab %} +{% endnavtabs %} + + +## Configure the Datastore + +{% include how-tos/steps/datastore.md %} \ No newline at end of file diff --git a/app/_how-tos/nonroot.md b/app/_how-tos/nonroot.md index 88f8a7546..9d89a2fe3 100644 --- a/app/_how-tos/nonroot.md +++ b/app/_how-tos/nonroot.md @@ -21,7 +21,7 @@ tldr: prereqs: inline: - title: Install {{site.base_gateway}} on Ubuntu - include_content: prereqs/install/ee/ubuntu + include_content: prereqs/install/gateway/ubuntu min_version: gateway: '3.4' diff --git a/app/_includes/how-tos/steps/datastore.md b/app/_includes/how-tos/steps/datastore.md new file mode 100644 index 000000000..7ca76a112 --- /dev/null +++ b/app/_includes/how-tos/steps/datastore.md @@ -0,0 +1,54 @@ +## 1. Configure PostgreSQL + +1. Switch to the default PostgreSQL user: + + ```sh + sudo -i -u postgres + ``` +1. Start the PostgreSQL shell: + + ``` + psql + ``` +1. Create a `kong` user and password: + + ``` + CREATE USER kong WITH PASSWORD 'super_secret'; + ``` +1. Create a database titled `kong` and assign the user as an owner: + + ``` + CREATE DATABASE kong OWNER kong; + ``` +1. Exit PostgreSQL, and exit the PostgreSQL shell: + + ``` + exit + ``` + +## 2. Run a {{site.base_gateway}} database migration + +`kong migrations` is used to configure the database for the first time. +Running `bootstrap` forces {{site.base_gateway}} to bootstrap the database set up in the previous step and run all of the migrations: + +```sh +kong migrations bootstrap +``` + +This command must be run as the `root` user. + +## 3. Validate + +You can validate that the datastore was configured correctly by starting {{site.base_gateway}}. + +1. Start {{site.base_gateway}}: + + ```sh + kong start + ``` +2. Verify the installation: + + ```sh + curl -i http://localhost:8001 + ``` +If you receive a `200` status code, {{site.base_gateway}} was configured correctly. \ No newline at end of file diff --git a/app/_includes/prereqs/install/ee/amazon-linux.md b/app/_includes/prereqs/install/ee/amazon-linux.md deleted file mode 100644 index 1f4eb6875..000000000 --- a/app/_includes/prereqs/install/ee/amazon-linux.md +++ /dev/null @@ -1,27 +0,0 @@ -{% navtabs %} -{% navtab "Manually installation" %} -1. Download {{site.base_gateway}}: - ```sh - curl -Lo kong-enterprise-edition-3.9.0.1.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/amzn/%{amzn}/%{_arch}/kong-enterprise-edition-3.9.0.1.aws.%{_arch}.rpm) - ``` - -2. Install {{site.base_gateway}}: - ``` - sudo yum install -y kong-enterprise-edition-3.9.0.1.rpm - ``` -{% endnavtab %} -{% navtab "Package manager" %} -1. Set up the package repository: - ```sh - curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=amzn&codename=$(rpm --eval '%{amzn}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo > /dev/null - ``` - ``` - sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' - ``` - -2. Install {{site.base_gateway}}: - ``` - sudo yum install -y kong-enterprise-edition-3.9.0.1 - ``` -{% endnavtab %} -{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/ee/debian.md b/app/_includes/prereqs/install/ee/debian.md deleted file mode 100644 index 1d2dcc96f..000000000 --- a/app/_includes/prereqs/install/ee/debian.md +++ /dev/null @@ -1,32 +0,0 @@ -{% navtabs %} -{% navtab "Manual installation" %} -1. Download {{site.base_gateway}}: -```sh -curl -Lo kong-enterprise-edition-3.9.0.1.deb "https://packages.konghq.com/public/gateway-39/deb/debian/pool/bullseye/main/k/ko/kong-enterprise-edition_3.9.0.1/kong-enterprise-edition_3.9.0.1_$(dpkg --print-architecture).deb" -``` - -2. Install {{site.base_gateway}}: - ``` - sudo apt install -y ./kong-enterprise-edition-3.9.0.1.deb - ``` -{% endnavtab %} -{% navtab "Package manager" %} -1. Set up the package repository: -```sh -curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg > /dev/null -``` -``` -curl -1sLf "https://packages.konghq.com/public/gateway-39/config.deb.txt?distro=debian&codename=$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/kong-gateway-39.list > /dev/null -``` -2. Update the package manager: - - ```sh - sudo apt update - ``` - -3. Install {{site.base_gateway}}: -``` -sudo apt install -y kong-enterprise-edition=3.9.0.1 -``` -{% endnavtab %} -{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/ee/red-hat.md b/app/_includes/prereqs/install/ee/red-hat.md deleted file mode 100644 index d990e1dac..000000000 --- a/app/_includes/prereqs/install/ee/red-hat.md +++ /dev/null @@ -1,27 +0,0 @@ -{% navtabs %} -{% navtab "Manual Installation" %} -1. Download {{site.base_gateway}}: - ```sh - curl -Lo kong-enterprise-edition-3.9.0.1.rpm $(rpm --eval https://packages.konghq.com/public/gateway-39/rpm/el/%{rhel}/%{_arch}/kong-enterprise-edition-3.9.0.1.el%{rhel}.%{_arch}.rpm) - ``` - -2. Install {{site.base_gateway}}: - ``` - sudo yum install -y kong-enterprise-edition-3.9.0.1.rpm - ``` -{% endnavtab %} -{% navtab "Package manager" %} -1. Set up the package repository: - ```sh - curl -1sLf "https://packages.konghq.com/public/gateway-39/config.rpm.txt?distro=el&codename=$(rpm --eval '%{rhel}')" | sudo tee /etc/yum.repos.d/kong-gateway-39.repo - ``` - ``` - sudo yum -q makecache -y --disablerepo='*' --enablerepo='kong-gateway-39' - ``` - -2. Install {{site.base_gateway}}: - ``` - sudo yum install -y kong-enterprise-edition-3.9.0.1 - ``` -{% endnavtab %} -{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/ee/ubuntu.md b/app/_includes/prereqs/install/ee/ubuntu.md deleted file mode 100644 index e8e33de37..000000000 --- a/app/_includes/prereqs/install/ee/ubuntu.md +++ /dev/null @@ -1,32 +0,0 @@ -{% navtabs %} -{% navtab "Manual installation" %} -1. Download {{site.base_gateway}}: -```sh -curl -Lo kong-enterprise-edition-3.9.0.1.deb "https://packages.konghq.com/public/gateway-39/deb/ubuntu/pool/noble/main/k/ko/kong-enterprise-edition_3.9.0.1/kong-enterprise-edition_3.9.0.1_$(dpkg --print-architecture).deb" -``` - -2. Install {{site.base_gateway}}: - ``` - sudo apt install -y ./kong-enterprise-edition-3.9.0.1.deb - ``` -{% endnavtab %} -{% navtab "Package manager" %} -1. Set up the package repository: -```sh -curl -1sLf "https://packages.konghq.com/public/gateway-39/gpg.B9DCD032B1696A89.key" | gpg --dearmor | sudo tee /usr/share/keyrings/kong-gateway-39-archive-keyring.gpg > /dev/null -``` -``` -curl -1sLf "https://packages.konghq.com/public/gateway-39/config.deb.txt?distro=debian&codename=$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/kong-gateway-39.list > /dev/null -``` -2. Update the package manager: - - ```sh - sudo apt update - ``` - -3. Install {{site.base_gateway}}: -``` -sudo apt install -y kong-enterprise-edition=3.9.0.1 -``` -{% endnavtab %} -{% endnavtabs %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/fips/ubuntu.md b/app/_includes/prereqs/install/fips/ubuntu.md index 5b1722973..5241eaec8 100644 --- a/app/_includes/prereqs/install/fips/ubuntu.md +++ b/app/_includes/prereqs/install/fips/ubuntu.md @@ -19,4 +19,8 @@ apt install -y kong-enterprise-edition-fips=3.9.1.0 4. Enable FIPS ```sh export KONG_FIPS=on && kong reload -``` \ No newline at end of file +``` + +## Configure the Datastore + +{% include how-tos/steps/datastore.md %} \ No newline at end of file diff --git a/app/_includes/prereqs/install/gateway/datastore-env-variables.md b/app/_includes/prereqs/install/gateway/datastore-env-variables.md new file mode 100644 index 000000000..f2b301351 --- /dev/null +++ b/app/_includes/prereqs/install/gateway/datastore-env-variables.md @@ -0,0 +1,10 @@ +Set the following variables so that `kong.conf` can interact with the datastore: + +```sh + export KONG_DATABASE=postgres + export KONG_PG_HOST=127.0.0.1 + export KONG_PG_PORT=5432 + export KONG_PG_USER=kong + export KONG_PG_PASSWORD=super_secret + export KONG_PG_DATABASE=kong +``` \ No newline at end of file diff --git a/app/_includes/prereqs/install/gateway/nonroot.md b/app/_includes/prereqs/install/gateway/nonroot.md new file mode 100644 index 000000000..9092e7641 --- /dev/null +++ b/app/_includes/prereqs/install/gateway/nonroot.md @@ -0,0 +1,33 @@ +## Running {{site.base_gateway}} as a non-root user + +When {{site.base_gateway}} is installed, the installation process creates the user group `kong`. Users that belong to the `kong` group can perform {{site.base_gateway}} actions. Adding your user to that user group will allow you to execute {{site.base_gateway}} commands on the system. + +{:.warning} +> **Warning:** The Nginx master process needs to run as `root` for Nginx to execute certain actions (for example, to listen on the privileged port 80). +>

+> Although running Kong as the `kong` user and group does provide more security, we advise that a system and network administration evaluation be performed before making this decision. Otherwise, Kong nodes might become unavailable due to insufficient permissions to execute privileged system calls in the operating system. + + + +You can check the permissions and ownership of the {{site.base_gateway}} in Linux like this: + +`ls -l /usr/local/kong` + +Which will return a list of subdirectories that contain a prefix like this: +`drwxrwxr-x 2 kong kong` + +The two `kong` values mean that the directory is owned by the user `kong` and the group `kong`. + +To make an existing user part of the `kong` group, you can run this command: + +`usermod -aG kong $USER` + +To view existing groups associated with the user, run: + +`groups $USER` + + +### Nginx + +In {{site.base_gateway}}, the Nginx master process runs at the `root` level so that Nginx can execute actions even if {{site.base_gateway}} is running as a non-root user. This is important when building containers. + diff --git a/app/_landing_pages/gateway/installation.yaml b/app/_landing_pages/gateway/installation.yaml new file mode 100644 index 000000000..509da6c04 --- /dev/null +++ b/app/_landing_pages/gateway/installation.yaml @@ -0,0 +1,33 @@ +metadata: + title: "{{site.base_gateway}} installation" + content_type: landing_page + description: Details {{site.base_gateway}} network, ports, and firewall settings and how to manage them. + tags: + - security + - traffic-control + breadcrumbs: + - /gateway/ + related_links: + - text: "{{site.base_gateway}} ports" + url: /gateway/network-ports-firewall/ + +rows: + - header: + type: h1 + text: "{{site.base_gateway}} network" + columns: + - blocks: + - type: structured_text + config: + blocks: + - type: text + text: | + @todo + + This is a landing page for all things networks, ports, and firewall for probably both Kong Gateway and Konnect + Can have some conceptual info, but mostly be a collection of cards/links to reference pages and how tos + + Source pages: + * https://docs.konghq.com/gateway/3.9.x/production/networking/dns-considerations/ + * https://docs.konghq.com/gateway/3.9.x/production/networking/cp-dp-proxy/ + * https://docs.konghq.com/konnect/network/ \ No newline at end of file diff --git a/app/gateway/installation.md b/app/gateway/installation.md index c7e147376..725b7d4ff 100644 --- a/app/gateway/installation.md +++ b/app/gateway/installation.md @@ -17,38 +17,7 @@ works_on: --- -## Linux -### Enterprise -{% navtabs %} -{% navtab "Debian" %} -{% include prereqs/install/ee/debian.md %} -{% endnavtab %} -{% navtab "Ubuntu" %} -{% include prereqs/install/ee/ubuntu.md %} -{% endnavtab %} -{% navtab "Amazon Linux" %} -{% include prereqs/install/ee/amazon-linux.md %} -{% endnavtab %} -{% navtab "Red Hat" %} -{% include prereqs/install/ee/red-hat.md %} -{% endnavtab %} -{% endnavtabs %} -### Open Source - -{% navtabs %} -{% navtab "Debian" %} -{% include prereqs/install/oss/debian.md %} -{% endnavtab %} -{% navtab "Ubuntu" %} -{% include prereqs/install/oss/ubuntu.md %} -{% endnavtab %} -{% navtab "Amazon Linux" %} -{% include prereqs/install/oss/amazon-linux.md %} -{% endnavtab %} -{% navtab "Red Hat" %} -{% include prereqs/install/oss/red-hat.md %} -{% endnavtab %} -{% endnavtabs %} +@TODO ### FIPS install @@ -65,36 +34,3 @@ works_on: {% endnavtab %} {% endnavtabs %} -## Running {{site.base_gateway}} as a non-root user - -When {{site.base_gateway}} is installed, the installation process creates the user group `kong`. Users that belong to the `kong` group can perform {{site.base_gateway}} actions. Adding your user to that user group will allow you to execute {{site.base_gateway}} commands on the system. - -{:.warning} -> **Warning:** The Nginx master process needs to run as `root` for Nginx to execute certain actions (for example, to listen on the privileged port 80). ->

-> Although running Kong as the `kong` user and group does provide more security, we advise that a system and network administration evaluation be performed before making this decision. Otherwise, Kong nodes might become unavailable due to insufficient permissions to execute privileged system calls in the operating system. - - - -You can check the permissions and ownership of the {{site.base_gateway}} in Linux like this: - -`ls -l /usr/local/kong` - -Which will return a list of subdirectories that contain a prefix like this: -`drwxrwxr-x 2 kong kong` - -The two `kong` values mean that the directory is owned by the user `kong` and the group `kong`. - -To make an existing user part of the `kong` group, you can run this command: - -`usermod -aG kong $USER` - -To view existing groups associated with the user, run: - -`groups $USER` - - -### Nginx - -In {{site.base_gateway}}, the Nginx master process runs at the `root` level so that Nginx can execute actions even if {{site.base_gateway}} is running as a non-root user. This is important when building containers. -