diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml new file mode 100644 index 000000000..8754a6790 --- /dev/null +++ b/.github/workflows/deploy-docs.yaml @@ -0,0 +1,13 @@ +name: Deploy documentation +on: + workflow_dispatch: + push: + branches: + - 'master' +jobs: + mkdocs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - run: pip install mkdocs mkdocs-material + - run: mkdocs gh-deploy \ No newline at end of file diff --git a/.gitignore b/.gitignore index 2d9cb419a..1be3dc826 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ .idea *version-info.json .DS_Store +site/ diff --git a/Makefile b/Makefile index 7abefe8e7..66c675525 100644 --- a/Makefile +++ b/Makefile @@ -86,7 +86,7 @@ transform-al2-to-al2023: hack/transform-al2-to-al2023.sh .PHONY: lint -lint: ## Check the source files for syntax and format issues +lint: lint-docs ## Check the source files for syntax and format issues $(SHFMT_COMMAND) $(SHFMT_FLAGS) --diff $(MAKEFILE_DIR) $(SHELLCHECK_COMMAND) --format gcc --severity error $(SHELL_FILES) @@ -130,7 +130,11 @@ k8s: validate ## Build default K8s version of EKS Optimized AL2 AMI .PHONY: 1.27 1.27: ## Build EKS Optimized AL2 AMI - K8s 1.27 $(MAKE) k8s kubernetes_version=1.27.3 kubernetes_build_date=2023-06-30 - + +.PHONY: lint-docs +lint-docs: ## Lint the docs + hack/lint-docs.sh + .PHONY: clean clean: rm *-manifest.json diff --git a/README.md b/README.md index 758fb9868..49eb62c26 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ The Makefile chooses a particular kubelet binary to use per Kubernetes version w ## 👩‍💻 Using the AMI -The [AMI user guide](doc/USER_GUIDE.md) has details about the AMI's internals, and the [EKS user guide](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-custom-ami) explains how to use a custom AMI in a managed node group. +The [AMI user guide](https://awslabs.github.io/amazon-eks-ami/USER_GUIDE/) has details about the AMI's internals, and the [EKS user guide](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-custom-ami) explains how to use a custom AMI in a managed node group. ## 🔒 Security diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md new file mode 120000 index 000000000..04c99a55c --- /dev/null +++ b/doc/CHANGELOG.md @@ -0,0 +1 @@ +../CHANGELOG.md \ No newline at end of file diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 2d6946816..5f030d149 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -46,7 +46,7 @@ When submitting PRs, we want to verify that there are no regressions in the AMI **Test #1: Verify that the unit tests pass** -Please add a test case for your changes, if possible. See the [unit test README](test/README.md) for more information. These tests will be run automatically for every pull request. +Please add a test case for your changes, if possible. See the [unit test README](https://github.com/awslabs/amazon-eks-ami/tree/master/test#readme) for more information. These tests will be run automatically for every pull request. ``` make test diff --git a/doc/README.md b/doc/README.md new file mode 120000 index 000000000..32d46ee88 --- /dev/null +++ b/doc/README.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/doc/USER_GUIDE.md b/doc/USER_GUIDE.md index b07ae7264..485b7ebc4 100644 --- a/doc/USER_GUIDE.md +++ b/doc/USER_GUIDE.md @@ -2,23 +2,11 @@ This document includes details about using the AMI template and the resulting AMIs. -1. [AMI template variables](#ami-template-variables) -1. [Building against other versions of Kubernetes binaries](#building-against-other-versions-of-kubernetes-binaries) -1. [Providing your own Kubernetes binaries](#providing-your-own-kubernetes-binaries) -1. [Container image caching](#container-image-caching) -1. [IAM permissions](#iam-permissions) -1. [Customizing kubelet config](#customizing-kubelet-config) -1. [AL2 and Linux kernel information](#al2-and-linux-kernel-information) -1. [Updating known instance types](#updating-known-instance-types) -1. [Version-locked packages](#version-locked-packages) -1. [Image credential provider plugins](#image-credential-provider-plugins) -1. [Ephemeral Storage](#ephemeral-storage) - --- ## AMI template variables -Default values for most variables are defined in [a default variable file](eks-worker-al2-variables.json). +Default values for most variables are defined in [a default variable file](https://github.com/awslabs/amazon-eks-ami/blob/master/eks-worker-al2-variables.json). Users have the following options for specifying their own values: @@ -310,7 +298,7 @@ If `kernel_version` is not set: - For Kubernetes 1.23 and below, `5.4` is used. - For Kubernetes 1.24 and above, `5.10` is used. -The [upgrade_kernel.sh script](../scripts/upgrade_kernel.sh) contains the logic for updating and upgrading the kernel. +The [upgrade_kernel.sh script](https://github.com/awslabs/amazon-eks-ami/blob/master/scripts/upgrade_kernel.sh) contains the logic for updating and upgrading the kernel. --- diff --git a/hack/lint-docs.sh b/hack/lint-docs.sh new file mode 100755 index 000000000..24ef64720 --- /dev/null +++ b/hack/lint-docs.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash + +set -o errexit +cd $(dirname $0) +./generate-template-variable-doc.py +if ! git diff --exit-code ../doc/USER_GUIDE.md; then + echo "ERROR: doc/USER_GUIDE.md is out of date. Please run hack/generate-template-variable-doc.py and commit the changes." + exit 1 +fi +./mkdocs.sh build --strict diff --git a/hack/mkdocs.Dockerfile b/hack/mkdocs.Dockerfile new file mode 100644 index 000000000..0f02dedce --- /dev/null +++ b/hack/mkdocs.Dockerfile @@ -0,0 +1,4 @@ +FROM python:3.9 +RUN pip install mkdocs mkdocs-material +WORKDIR /workdir +ENTRYPOINT ["mkdocs"] \ No newline at end of file diff --git a/hack/mkdocs.sh b/hack/mkdocs.sh new file mode 100755 index 000000000..4f7c93b95 --- /dev/null +++ b/hack/mkdocs.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash + +set -o errexit + +cd $(dirname $0) + +IMAGE_ID=$(docker build --file mkdocs.Dockerfile --quiet .) +cd .. + +if [[ "$*" =~ "serve" ]]; then + EXTRA_ARGS="${EXTRA_ARGS} -a 0.0.0.0:8000" +fi + +docker run --rm -v ${PWD}:/workdir -p 8000:8000 ${IMAGE_ID} "${@}" ${EXTRA_ARGS} diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 000000000..56ec4c37e --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,19 @@ +site_name: Amazon EKS AMI +docs_dir: doc/ +site_description: Build template and runtime resources for the Amazon EKS AMI +repo_name: awslabs/amazon-eks-ami +repo_url: https://github.com/awslabs/amazon-eks-ami +nav: + - 'Overview': README.md + - 'User Guide': USER_GUIDE.md + - 'Changelog': CHANGELOG.md + - 'Community': + - 'Contribution guidelines': CONTRIBUTING.md + - 'Code of Conduct': CODE_OF_CONDUCT.md + +theme: + name: material + palette: + primary: black + features: + - navigation.sections \ No newline at end of file