diff --git a/.github/workflows/linkcheck.json b/.github/workflows/linkcheck.json new file mode 100644 index 00000000..a8a89253 --- /dev/null +++ b/.github/workflows/linkcheck.json @@ -0,0 +1,27 @@ +{ + "timeout": "5s", + "retryOn429": true, + "retryCount": 5, + "fallbackRetryDelay": "30s", + "aliveStatusCodes": [200, 206], + "httpHeaders": [ + { + "urls": ["https://help.github.com/"], + "headers": { + "Accept-Encoding": "zstd, br, gzip, deflate" + } + } + ], + "ignorePatterns": [ + { + "pattern": [ + "localhost" + ] + }, + { + "pattern": [ + "127.0.0.1" + ] + } + ] +} \ No newline at end of file diff --git a/.github/workflows/markdown-link-check.yml b/.github/workflows/markdown-link-check.yml new file mode 100644 index 00000000..b3b536b5 --- /dev/null +++ b/.github/workflows/markdown-link-check.yml @@ -0,0 +1,37 @@ +name: Check Markdown links + +on: + push: + branches: + - main + paths: + - "**/*.md" + + pull_request: + branches: + - main + paths: + - "**/*.md" + +permissions: + contents: read + +jobs: + markdown-link-check: + runs-on: ubuntu-latest + steps: + - name: Harden Runner + uses: step-security/harden-runner@v2 + with: + egress-policy: audit + + - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 + - uses: actions/setup-node@v4 + with: + node-version: '16.x' + - name: install markdown-link-check + run: npm install -g markdown-link-check@3.10.2 + - name: markdown-link-check version + run: npm list -g markdown-link-check + - name: Run markdown-link-check on MD files + run: find docs -name "*.md" | xargs -n 1 markdown-link-check -q -c .github/workflows/linkcheck.json \ No newline at end of file diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 00000000..af4ea97d --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,47 @@ +name: Publish docs via GitHub Pages +on: + push: + branches: + - main + +env: + PYTHON_VERSION: 3.x + +permissions: + contents: read + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Harden Runner + uses: step-security/harden-runner@v2 + with: + egress-policy: audit + + - name: Checkout main + uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 + with: + fetch-depth: 0 + + - name: Set up Python ${{ env.PYTHON_VERSION }} + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION }} + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install mkdocs-material==9.5.21 \ + mkdocs-include-markdown-plugin==6.0.6 \ + mkdocs-awesome-pages-plugin==2.9.2 + + - name: git config + run: | + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + + - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/.github/workflows/scorecards.yml b/.github/workflows/scorecards.yml new file mode 100644 index 00000000..15f9d38a --- /dev/null +++ b/.github/workflows/scorecards.yml @@ -0,0 +1,76 @@ +# This workflow uses actions that are not certified by GitHub. They are provided +# by a third-party and are governed by separate terms of service, privacy +# policy, and support documentation. + +name: Scorecard supply-chain security +on: + # For Branch-Protection check. Only the default branch is supported. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection + branch_protection_rule: + # To guarantee Maintained check is occasionally updated. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained + schedule: + - cron: '20 7 * * 2' + push: + branches: ["main"] + +# Declare default permissions as read only. +permissions: read-all + +jobs: + analysis: + name: Scorecard analysis + runs-on: ubuntu-latest + permissions: + # Needed to upload the results to code-scanning dashboard. + security-events: write + # Needed to publish results and get a badge (see publish_results below). + id-token: write + contents: read + actions: read + + steps: + - name: Harden Runner + uses: step-security/harden-runner@55d479fb1c5bcad5a4f9099a5d9f37c8857b2845 # v2.4.1 + with: + egress-policy: audit + + - name: "Checkout code" + uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.5.4 + with: + persist-credentials: false + + - name: "Run analysis" + uses: ossf/scorecard-action@dc50aa9510b46c811795eb24b2f1ba02a914e534 # v2.3.3 + with: + results_file: results.sarif + results_format: sarif + # (Optional) "write" PAT token. Uncomment the `repo_token` line below if: + # - you want to enable the Branch-Protection check on a *public* repository, or + # - you are installing Scorecards on a *private* repository + # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat. + # repo_token: ${{ secrets.SCORECARD_TOKEN }} + + # Public repositories: + # - Publish results to OpenSSF REST API for easy access by consumers + # - Allows the repository to include the Scorecard badge. + # - See https://github.com/ossf/scorecard-action#publishing-results. + # For private repositories: + # - `publish_results` will always be set to `false`, regardless + # of the value entered here. + publish_results: true + + # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF + # format to the repository Actions tab. + - name: "Upload artifact" + uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3 + with: + name: SARIF file + path: results.sarif + retention-days: 5 + + # Upload the results to GitHub's code scanning dashboard. + - name: "Upload to code-scanning" + uses: github/codeql-action/upload-sarif@9fdb3e49720b44c48891d036bb502feb25684276 # v3.25.6 + with: + sarif_file: results.sarif \ No newline at end of file diff --git a/bootstrap/terraform/main.tf b/bootstrap/terraform/main.tf index dcdfa6a0..4f51e50e 100644 --- a/bootstrap/terraform/main.tf +++ b/bootstrap/terraform/main.tf @@ -148,8 +148,9 @@ module "eks_blueprints_addons" { enable_argocd = true argocd = { namespace = "argocd" - chart_version = "6.11.1" # ArgoCD v2.11.2 + chart_version = "7.1.0" # ArgoCD v2.11.2 wait = true + wait_for_jobs = true timeout = "600" values = [ templatefile("${path.module}/values/argocd.yaml", { @@ -160,8 +161,9 @@ module "eks_blueprints_addons" { } enable_gatekeeper = true gatekeeper = { - timeout = "600" - wait = true + wait = true + wait_for_jobs = true + timeout = "600" } enable_metrics_server = true @@ -169,9 +171,10 @@ module "eks_blueprints_addons" { enable_kube_prometheus_stack = true kube_prometheus_stack = { - wait = true - timeout = "600" - values = [file("${path.module}/values/prometheus.yaml")] + wait = true + wait_for_jobs = true + timeout = "600" + values = [file("${path.module}/values/prometheus.yaml")] } depends_on = [module.eks.eks_managed_node_groups] diff --git a/bootstrap/terraform/values/argocd.yaml b/bootstrap/terraform/values/argocd.yaml index 195677dd..e693d783 100644 --- a/bootstrap/terraform/values/argocd.yaml +++ b/bootstrap/terraform/values/argocd.yaml @@ -12,8 +12,8 @@ controller: annotations: prometheus.io/scrape: true env: - - name: ARGOCD_K8S_CLIENT_QPS #required for Crossplane too many CRDs https://github.com/argoproj/argo-cd/pull/448 - value: "300" + - name: ARGOCD_K8S_CLIENT_QPS #required for Crossplane too many CRDs https://github.com/argoproj/argo-cd/pull/448 + value: "300" repoServer: autoscaling: @@ -21,8 +21,8 @@ repoServer: minReplicas: 1 resources: # Adjust based on your specific use case (required for HPA) requests: - cpu : "100m" - memory : "256Mi" + cpu: "100m" + memory: "256Mi" limits: cpu: "200m" memory: "512Mi" @@ -46,8 +46,8 @@ server: minReplicas: 1 resources: # Adjust based on your specific use case (required for HPA) requests: - cpu : "100m" - memory : "256Mi" + cpu: "100m" + memory: "256Mi" limits: cpu: "200m" memory: "512Mi" @@ -58,7 +58,7 @@ server: prometheus.io/scrape: true service: type: "LoadBalancer" - annotations: + annotations: service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing" configs: diff --git a/bootstrap/terraform/variables.tf b/bootstrap/terraform/variables.tf index 110197fe..41d67577 100644 --- a/bootstrap/terraform/variables.tf +++ b/bootstrap/terraform/variables.tf @@ -16,7 +16,7 @@ variable "name" { variable "cluster_version" { type = string description = "Kubernetes Version" - default = "1.30" + default = "1.29" } variable "capacity_type" { diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 00000000..b2e60dfd --- /dev/null +++ b/docs/.pages @@ -0,0 +1,5 @@ +nav: + - Overview: index.md + - Getting Started: getting-started.md + - Patterns: patterns + - FAQ: faq.md diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..04cd6216 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,18 @@ +# Frequently Asked Questions + +## Timeouts on destroy + +Customers who are deleting their environments using `terraform destroy` may see timeout errors when VPCs are being deleted. This is due to a known issue in the [vpc-cni](https://github.com/aws/amazon-vpc-cni-k8s/issues/1223#issue-704536542) + +Customers may face a situation where ENIs that were attached to EKS managed nodes (same may apply to self-managed nodes) are not being deleted by the VPC CNI as expected which leads to IaC tool failures, such as: + +* ENIs are left on subnets +* EKS managed security group which is attached to the ENI can’t be deleted by EKS + +The current recommendation is to execute cleanup in the following order: + +1. delete all pods that have been created in the cluster. +2. add delay/ wait +3. delete VPC CNI +4. delete nodes +5. delete cluster \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..4e410a4c --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,70 @@ +# Getting Started + +This getting started guide will help you bootstrap your first cluster using Crossplane Blueprints. + +## Prerequisites + +Ensure that you have installed the following tools locally: + +- [awscli](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) +- [kubectl](https://Kubernetes.io/docs/tasks/tools/) +- [terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) + +## Deploy + +### eksctl + +1. TBD + +### terraform + +1. For consuming Crossplane Blueprints, please see the [Getting Started](https://awslabs.github.io/crossplane-on-eks/#getting-started) section. For exploring and trying out the patterns provided, please +clone the project locally to quickly get up and running with a pattern. After cloning the project locally, `cd` into the pattern +directory of your choice. + +2. To provision the pattern, the typical steps of execution are as follows: + + ```sh + terraform init + terraform apply -target="module.vpc" -auto-approve + terraform apply -target="module.eks" -auto-approve + terraform apply -target="module.eks_blueprints_addons" -auto-approve + terraform apply -target="module.crossplane" -auto-approve + terraform apply -auto-approve + ``` + +3. Once all of the resources have successfully been provisioned, the following command can be used to update the `kubeconfig` +on your local machine and allow you to interact with your EKS Cluster using `kubectl`. + + ```sh + aws eks --region update-kubeconfig --name --alias + ``` + + !!! info "Terraform outputs" + The examples will output the `aws eks update-kubeconfig ...` command as part of the Terraform apply output to simplify this process for users + +4. Once you have updated your `kubeconfig`, you can verify that you are able to interact with your cluster by running the following command: + + ```sh + kubectl get nodes + ``` + + This should return a list of the node(s) running in the cluster created. If any errors are encountered, please re-trace the steps above + and consult the pattern's `README.md` for more details on any additional/specific steps that may be required. + +## Destroy + +To teardown and remove the resources created in the bootstrap, the typical steps of execution are as follows: + +```sh +terraform destroy -target="module.crossplane" -auto-approve +terraform destroy -target="module.eks_blueprints_addons" -auto-approve +terraform destroy -target="module.eks" -auto-approve +terraform destroy -target="module.vpc" -auto-approve +terraform destroy -auto-approve +``` + +!!! danger "Resources created outside of Terraform" + Some resources may have been created that Terraform is not aware of that will cause issues + when attempting to clean up the pattern. Please see the `destroy.md` for more + details. \ No newline at end of file diff --git a/docs/images/colored-logo.png b/docs/images/colored-logo.png new file mode 100644 index 00000000..d49129e3 Binary files /dev/null and b/docs/images/colored-logo.png differ diff --git a/docs/images/white-logo.png b/docs/images/white-logo.png new file mode 100644 index 00000000..004fcf1a Binary files /dev/null and b/docs/images/white-logo.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..4129e67e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +{% + include-markdown "../README.md" +%} diff --git a/docs/debugging.md b/docs/patterns/debugging.md similarity index 98% rename from docs/debugging.md rename to docs/patterns/debugging.md index dc9d0f61..bfece807 100644 --- a/docs/debugging.md +++ b/docs/patterns/debugging.md @@ -32,7 +32,7 @@ Most error messages are logged to resources' event field. Whenever your Composit _Note:_ Debugging is also enabled for the AWS provider pods. You may find it useful to check the logs for the provider pods for extra information on failures. You can also disable logging -[here](/bootstrap/eksctl/crossplane/aws-provider.yaml#L24). +[here](../../bootstrap/eksctl/crossplane/aws-provider.yaml#L24). ```bash # kubectl get pods -n crossplane-system @@ -145,7 +145,7 @@ Debugging Composition Definitions is similar to debugging Compositions. ### Providers There are two ways to install providers in Crossplane. Using `configuration.pkg.crossplane.io` and `provider.pkg.crossplane.io`. In this repository, we use `provider.pkg.crossplane.io`. -Note that if you define a `configuration.pkg.crossplane.io` object, Crossplane will create a `provider.pkg.crossplane.io` object. This object is managed by Crossplane. Please refer to [this guide](https://github.com/crossplane/crossplane/blob/master/docs/concepts/packages.md) for more information about Crossplane Packages. +Note that if you define a `configuration.pkg.crossplane.io` object, Crossplane will create a `provider.pkg.crossplane.io` object. This object is managed by Crossplane. Please refer to [this guide](https://docs.crossplane.io/latest/concepts/packages/) for more information about Crossplane Packages. If you are experiencing provider issues, steps below are a good starting point. diff --git a/docs/nested-compositions.md b/docs/patterns/nested-compositions.md similarity index 98% rename from docs/nested-compositions.md rename to docs/patterns/nested-compositions.md index 25ff63e7..a25d5105 100644 --- a/docs/nested-compositions.md +++ b/docs/patterns/nested-compositions.md @@ -4,7 +4,7 @@ Compositions can be nested within a composition. Take a look at the example-appl An example yaml file to deploy this Composition is available at `examples/aws-provider/composite-resources/example-application/example-application.yaml`. -Install the AWS Compositions and XRDs following the instructions in [compositions/README.md](../compositions/README.md) +Install the AWS Compositions and XRDs following the instructions in [compositions/README.md](../../compositions/README.md) Let’s take a look at how this example application can be deployed. diff --git a/docs/patching-101.md b/docs/patterns/patching-101.md similarity index 100% rename from docs/patching-101.md rename to docs/patterns/patching-101.md diff --git a/docs/rds-day-2.md b/docs/patterns/rds-day-2.md similarity index 100% rename from docs/rds-day-2.md rename to docs/patterns/rds-day-2.md diff --git a/docs/vault-integration.md b/docs/patterns/vault-integration.md similarity index 91% rename from docs/vault-integration.md rename to docs/patterns/vault-integration.md index 3a97b019..ff71992b 100644 --- a/docs/vault-integration.md +++ b/docs/patterns/vault-integration.md @@ -19,7 +19,7 @@ Following command line tools: Note: - As of Crossplane 1.9.0, the support for external secret store is still in alpha state and may go under changes. - This assumes a use case for single-cluster multi-tenant. However, the underlying concepts discussed here should be applicable to multi-cluster setup as well. -- This doc is based on the excellent [vault secret store guide](https://github.com/crossplane/crossplane/blob/master/docs/guides/vault-as-secret-store.md#prepare-vault) and [external vault configuration guide](https://learn.hashicorp.com/tutorials/vault/kubernetes-external-vault). Please check these guides out for more detailed information. +- This doc is based on the excellent [external vault configuration guide](https://learn.hashicorp.com/tutorials/vault/kubernetes-external-vault). Please check these guides out for more detailed information. # Procedure @@ -34,7 +34,7 @@ eksctl create cluster -f bootstrap/eksctl/eksctl.yaml You can create a vault service in the same cluster as Crossplane or create a service on a VM. ### In-cluster -Follow: https://github.com/crossplane/crossplane/blob/master/docs/guides/vault-as-secret-store.md#prepare-vault +Follow: https://docs.crossplane.io/latest/guides/vault-as-secret-store/ ### On an external VM This VM must be reachable by the Crossplane installation. If you are using an EC2 instance, routing, network ACL, and Security Groups must be configured to allow for traffic from Crossplane pod to the VM. @@ -161,7 +161,7 @@ helm upgrade --install crossplane crossplane-stable/crossplane --namespace cross Once Crossplane is installed, install its AWS provider. -Update the [AWS provider YAML file](../bootstrap/eksctl/crossplane/aws-provider-vault-secret.yaml) with your role ARN, then execute the following commands. +Update the [AWS provider YAML file](../../bootstrap/eksctl/crossplane/aws-provider-vault-secret.yaml) with your role ARN, then execute the following commands. ```bash kubectl apply -f bootstrap/eksctl/crossplane/aws-provider-vault-secret.yaml @@ -173,7 +173,7 @@ kubectl get ProviderRevision `StoreConfig` objects provides Crossplane and its providers information about how to connect to secret stores. These objects must be configured for external secret integrations to work. -Update the [store config YAML file](../bootstrap/eksctl/crossplane/store-config-vault.yaml) with your endpoint information. If you configured vault outside of the cluster, it should be the private IP address. e.g. `10.0.0.1:8200` +Update the [store config YAML file](../../bootstrap/eksctl/crossplane/store-config-vault.yaml) with your endpoint information. If you configured vault outside of the cluster, it should be the private IP address. e.g. `10.0.0.1:8200` ```bash kubectl apply -f bootstrap/eksctl/crossplane/store-config-vault.yaml @@ -219,7 +219,7 @@ kubectl describe bucket # ---- ------ ---- ---- ------- # Warning CannotConnectToProvider 1s (x5 over 14s) managed/bucket.s3.aws.crossplane.io cannot get referenced Provider: ProviderConfig.aws.crossplane.io "default-provider-config" not found ``` -In the [claim file](../examples/aws-provider/composite-resources/s3/multi-tenant.yaml), we specify a provider config name. However, this is patched out to use the provider config with name `-provider-config`. This is why the error message indicates provider config with name `default-provider-config` is not found. +In the [claim file](../../examples/aws-provider/composite-resources/s3/multi-tenant.yaml), we specify a provider config name. However, this is patched out to use the provider config with name `-provider-config`. This is why the error message indicates provider config with name `default-provider-config` is not found. Since we created a provider config named `application1-provider-config`, we should be able to create a claim in namespace called application1. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..71d755cc --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,67 @@ +site_name: Amazon Crossplane Blueprints +docs_dir: docs/ +copyright: Copyright © Amazon 2024 +site_author: AWS +site_url: https://awslabs.github.io/crossplane-on-eks/ +repo_name: crossplane-on-eks +repo_url: https://github.com/awslabs/crossplane-on-eks + +theme: + name: material + logo: images/white-logo.png + favicon: images/colored-logo.png + font: + text: ember + palette: + primary: orange + accent: orange + icon: + repo: fontawesome/brands/github + admonition: + note: octicons/tag-16 + abstract: octicons/checklist-16 + info: octicons/info-16 + tip: octicons/squirrel-16 + success: octicons/check-16 + question: octicons/question-16 + warning: octicons/alert-16 + failure: octicons/x-circle-16 + danger: octicons/zap-16 + bug: octicons/bug-16 + example: octicons/beaker-16 + quote: octicons/quote-16 + features: + - navigation.tabs.sticky + highlightjs: true + hljs_languages: + - yaml + - json + +plugins: + - include-markdown + - search: + lang: + - en + - awesome-pages + +extra: + version: + provider: mike + +markdown_extensions: + - attr_list + - admonition + - codehilite + - footnotes + - md_in_html + - pymdownx.critic + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - toc: + permalink: true