diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 000000000..4a9058b79 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "website/themes/docsy"] + path = website/themes/docsy + url = https://github.com/google/docsy.git diff --git a/website/Makefile b/website/Makefile new file mode 100644 index 000000000..1abfda104 --- /dev/null +++ b/website/Makefile @@ -0,0 +1,19 @@ +bootstrap: + git submodule update --init --recursive + npm i + +serve: bootstrap + hugo server \ + --buildDrafts \ + --buildFuture \ + --disableFastRender + +production-build: bootstrap + hugo --minify + +preview-build: bootstrap + hugo \ + --baseURL $(DEPLOY_PRIME_URL) \ + --buildDrafts \ + --buildFuture \ + --minify diff --git a/website/README.md b/website/README.md new file mode 100644 index 000000000..016f62926 --- /dev/null +++ b/website/README.md @@ -0,0 +1,60 @@ +# Azure Key Vault Provider for Secrets Store CSI Driver documentation + +If you are looking to explore the Azure Key Vault Provider for Secrets Store CSI Driver documentation, please go to the documentation website: + +[**https://azure.github.io/secrets-store-csi-driver-provider-azure/**](https://azure.github.io/secrets-store-csi-driver-provider-azure/) + +This repo contains the markdown files which generate the above website. See below for guidance on running with a local environment to contribute to the docs. + +## Contribution guidelines + +Before making your first contribution, make sure to review the [Contributing Guidelines](https://azure.github.io/secrets-store-csi-driver-provider-azure/contribution-guidelines/) in the docs. + +## Overview + +The Azure Key Vault Provider for Secrets Store CSI Driver docs are built using [Hugo](https://gohugo.io/) with the [Docsy](https://docsy.dev) theme, hosted using [GitHub Pages](https://pages.github.com/). + +The [website](./website) directory contains the hugo project, markdown files, and theme configurations. + +## Pre-requisites + +- [Hugo extended version](https://gohugo.io/getting-started/installing) +- [Node.js](https://nodejs.org/en/) + +## Environment setup + +1. Ensure pre-requisites are installed +2. Clone this repository +```sh +git clone https://github.com/Azure/secrets-store-csi-driver-provider-azure.git +``` +3. Change to website directory: +```sh +cd website +``` +4. Add Docsy submodule: +```sh +git submodule add https://github.com/google/docsy.git themes/docsy +``` +5. Update submodules: +```sh +git submodule update --init --recursive +``` +6. Install npm packages: +```sh +npm install +``` + +## Run local server +1. Make sure you're still in the `website` directory +2. Run +```sh +hugo server --disableFastRender +``` +3. Navigate to `http://localhost:1313/docs` + +## Update docs +1. Create new branch +1. Commit and push changes to content +1. Submit pull request to `master` +1. Staging site will automatically get created and linked to PR to review and test diff --git a/website/assets/scss/_variables_project.scss b/website/assets/scss/_variables_project.scss new file mode 100644 index 000000000..256902739 --- /dev/null +++ b/website/assets/scss/_variables_project.scss @@ -0,0 +1,6 @@ +/* + +Add styles or override variables from the theme here. + +*/ + diff --git a/website/config.toml b/website/config.toml new file mode 100644 index 000000000..0c00f2dfa --- /dev/null +++ b/website/config.toml @@ -0,0 +1,191 @@ +baseURL = "https://azure.github.io/secrets-store-csi-driver-provider-azure" +title = "Azure Key Vault Provider for Secrets Store CSI Driver" + +enableRobotsTXT = true + + +# Hugo allows theme composition (and inheritance). The precedence is from left to right. +theme = ["docsy"] + +# Will give values to .Lastmod etc. +enableGitInfo = false + +# Language settings +contentDir = "content/en" +defaultContentLanguage = "en" +defaultContentLanguageInSubdir = false +# Useful when translating. +enableMissingTranslationPlaceholders = true + +disableKinds = ["taxonomy", "taxonomyTerm"] + +# Highlighting config +pygmentsCodeFences = true +pygmentsUseClasses = false +# Use the new Chroma Go highlighter in Hugo. +pygmentsUseClassic = false +#pygmentsOptions = "linenos=table" +# See https://help.farbox.com/pygments.html +pygmentsStyle = "tango" + +# Configure how URLs look like per section. +[permalinks] +blog = "/:section/:year/:month/:day/:slug/" + +## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday +[blackfriday] +plainIDAnchors = true +hrefTargetBlank = true +angledQuotes = false +latexDashes = true + +# Image processing configuration. +[imaging] +resampleFilter = "CatmullRom" +quality = 75 +anchor = "smart" + +[services] +[services.googleAnalytics] +# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback]. +# id = "UA-00000000-0" + +# Language configuration + +[languages] +[languages.en] +title = "Azure Key Vault Provider for Secrets Store CSI Driver" +description = "Azure Key Vault Provider for Secrets Store CSI Driver project documentation site" +languageName ="English" +# Weight used for sorting. +weight = 1 +#[languages.no] +#title = "" +#description = "" +#languageName ="" +#contentDir = "content/no" +time_format_default = "02.01.2006" +time_format_blog = "02.01.2006" + +[markup] + [markup.goldmark] + [markup.goldmark.renderer] + unsafe = true + [markup.highlight] + # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html + style = "tango" + # Uncomment if you want your chosen highlight style used for code blocks without a specified language + # guessSyntax = "true" + +# Everything below this are Site Params + +[params] +copyright = "Azure Compute OSS Upstream Team" +#privacy_policy = "https://policies.google.com/privacy" + +# First one is picked as the Twitter card image if not set on page. +# images = ["images/project-illustration.png"] + +# Menu title if your navbar has a versions selector to access old versions of your site. +# This menu appears only if you have at least one [params.versions] set. +version_menu = "Releases" + +# Flag used in the "version-banner" partial to decide whether to display a +# banner on every page indicating that this is an archived version of the docs. +# Set this flag to "true" if you want to display the banner. +archived_version = false + +# The version number for the version of the docs represented in this doc set. +# Used in the "version-banner" partial to display a version number for the +# current doc set. +version = "0.0" + +# A link to latest version of the docs. Used in the "version-banner" partial to +# point people to the main doc site. +url_latest_version = "https://azure.github.io/secrets-store-csi-driver-provider-azure/" + +# Repository configuration (URLs for in-page links to opening issues and suggesting changes) +github_repo = "https://github.com/Azure/secrets-store-csi-driver-provider-azure" +# An optional link to a related project repo. For example, the sibling repository where your product code lives. +github_project_repo = "https://github.com/Azure/secrets-store-csi-driver-provider-azure/issues/new?assignees=&labels=bug&template=bug-report.md&title=" + +# Specify a value here if your content directory is not in your repo's root directory +# github_subdir = "website" + +# Google Custom Search Engine ID. Remove or comment out to disable search. +# gcs_engine_id = "011737558837375720776:fsdu1nryfng" + +# Enable Algolia DocSearch +algolia_docsearch = false + +# Enable Lunr.js offline search +offlineSearch = true +offlineSearchSummaryLength = 70 +offlineSearchMaxResults = 10 + +# Enable syntax highlighting and copy buttons on code blocks with Prism +prism_syntax_highlighting = false + +# User interface configuration +[params.ui] +# Enable to show the side bar menu in its compact state. +sidebar_menu_compact = false +# Set to true to disable breadcrumb navigation. +breadcrumb_disable = false +# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) +sidebar_search_disable = true +# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar +navbar_logo = false +# Set to true to disable the About link in the site footer +footer_about_disable = true + +# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. +# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. +# If you want this feature, but occasionally need to remove the "Feedback" section from a single page, +# add "hide_feedback: true" to the page's front matter. +[params.ui.feedback] +enable = true +# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). +yes = 'Glad to hear it! Please tell us how we can improve.' +no = 'Sorry to hear that. Please tell us how we can improve.' + +# Adds a reading time to the top of each doc. +# If you want this feature, but occasionally need to remove the Reading time from a single page, +# add "hide_readingtime: true" to the page's front matter +[params.ui.readingtime] +enable = false + +[params.links] +# End user relevant links. These will show up on left side of footer and in the community page if you have one. +[[params.links.user]] + name = "Slack" + url = "https://kubernetes.slack.com/archives/C013PUP2WRK" + icon = "fab fa-slack" + desc = "Chat with other project developers" +#[[params.links.user]] +# name = "User mailing list" +# url = "https://example.org/mail" +# icon = "fa fa-envelope" +# desc = "Discussion and help from your fellow users" +#[[params.links.user]] +# name ="Twitter" +# url = "https://example.org/twitter" +# icon = "fab fa-twitter" +# desc = "Follow us on Twitter to get the latest news!" +#[[params.links.user]] +# name = "Stack Overflow" +# url = "https://example.org/stack" +# icon = "fab fa-stack-overflow" +# desc = "Practical questions and curated answers" +# Developer relevant links. These will show up on right side of footer and in the community page if you have one. +[[params.links.developer]] + name = "GitHub" + url = "https://github.com/Azure/secrets-store-csi-driver-provider-azure" + icon = "fab fa-github" + desc = "Development takes place here!" +#[[params.links.developer]] +# name = "Developer mailing list" +# url = "https://example.org/mail" +# icon = "fa fa-envelope" +# desc = "Discuss development issues around the project" + diff --git a/website/content/en/_index.md b/website/content/en/_index.md new file mode 100644 index 000000000..b8faac35a --- /dev/null +++ b/website/content/en/_index.md @@ -0,0 +1,32 @@ + +--- +type: docs +title: "Azure Key Vault Provider for Secrets Store CSI Driver" +linkTitle: "Documentation" +weight: 20 +menu: + main: + weight: 20 +--- + +Azure Key Vault provider for [Secrets Store CSI driver](https://github.com/kubernetes-sigs/secrets-store-csi-driver) allows you to get secret contents stored in an [Azure Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/general/overview) instance and use the Secrets Store CSI driver interface to mount them into Kubernetes pods. + +## Features + +- Mounts secrets/keys/certs on pod start using a CSI volume +- Supports mounting multiple secrets store objects as a single volume +- Supports pod identity to restrict access with specific identities +- Supports pod portability with the SecretProviderClass CRD +- Supports windows containers (Kubernetes version v1.18+) +- Supports sync with Kubernetes Secrets (Secrets Store CSI Driver v0.0.10+) +- Supports multiple secrets stores providers in the same cluster. + +### Secret Content is Mounted on Pod Start +On pod start and restart, the driver will call the Azure provider binary to retrieve the secret content from the Azure Key Vault instance you have specified in the `SecretProviderClass` custom resource. Then the content will be mounted to the container's file system. + +To validate, once the pod is started, you should see the new mounted content at the volume path specified in your deployment yaml. + +```bash +kubectl exec -it nginx-secrets-store-inline ls /mnt/secrets-store/ +foo +``` diff --git a/website/content/en/configurations/_index.md b/website/content/en/configurations/_index.md new file mode 100644 index 000000000..4d84eb49f --- /dev/null +++ b/website/content/en/configurations/_index.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "Configurations" +linkTitle: "Configurations" +weight: 4 +description: > + An overview of all the configuration features of Azure KeyVault Provider for Secrets Store CSI Driver +--- \ No newline at end of file diff --git a/website/content/en/configurations/custom-environments.md b/website/content/en/configurations/custom-environments.md new file mode 100644 index 000000000..643c2e200 --- /dev/null +++ b/website/content/en/configurations/custom-environments.md @@ -0,0 +1,39 @@ +--- +type: docs +title: "Custom Azure Environments" +linkTitle: "Custom Azure Environments" +weight: 5 +description: > + Pull secret content from KeyVault instances hosted on air-gapped and/or on-prem Azure clouds +--- + +In order to pull secret content from Key Vault instances hosted on air-gapped and/or on-prem Azure clouds, +your `SecretProviderClass` resource must include the following: + +```yaml +parameters: + cloudName: "AzureStackCloud" + cloudEnvFileName: "/path/to/custom/environment.json +``` + +Parameter `cloudEnvFileName` should be the path to a JSON file that contains the custom cloud environment details that +[azure-sdk-for-go](https://github.com/Azure/azure-sdk-for-go) needs to interact with the target Key Vault instance. + +Typically, the custom cloud environment file is stored in the file system of the Kubernetes node +and accessible to the `secrets-store-csi-driver` pods through a mounted volume. + +Even if the target cloud is not an Azure Stack Hub cloud, cloud name must be set to `"AzureStackCloud"` +to signal `azure-sdk-for-go` to load the custom cloud environment details from `cloudEnvFileName`. + +## Environment files + +The custom cloud environment sample below shows the minimum set of properties required by `secrets-store-csi-driver-provider-azure`. + +```json +{ + "name": "AzureStackCloud", + "activeDirectoryEndpoint": "https://login.microsoftonline.com/", + "keyVaultEndpoint": "https://vault.azure.net/", + "keyVaultDNSSuffix": "vault.azure.net" +} +``` diff --git a/website/content/en/configurations/enable-auto-rotation-secrets.md b/website/content/en/configurations/enable-auto-rotation-secrets.md new file mode 100644 index 000000000..98f4721fc --- /dev/null +++ b/website/content/en/configurations/enable-auto-rotation-secrets.md @@ -0,0 +1,12 @@ +--- +type: docs +title: "Enable Auto Rotation of Secrets" +linkTitle: "Enable Auto Rotation of Secrets" +weight: 2 +description: > + Periodically update the pod mount and Kubernetes Secret with the latest content from external secrets store +--- + +You can setup the Secrets Store CSI Driver to periodically update the pod mount and Kubernetes Secret with the latest content from external secrets-store. Refer to [doc](https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/master/docs/README.rotation.md) for steps on enabling auto rotation. + +**NOTE** The CSI driver **does not restart** the application pods. It only handles updating the pod mount and Kubernetes secret similar to how Kubernetes handles updates to Kubernetes secret mounted as volumes. \ No newline at end of file diff --git a/website/content/en/configurations/getting-certs-and-keys.md b/website/content/en/configurations/getting-certs-and-keys.md new file mode 100644 index 000000000..3a6f3a26e --- /dev/null +++ b/website/content/en/configurations/getting-certs-and-keys.md @@ -0,0 +1,64 @@ +--- +type: docs +title: "Getting Certificates and Keys using Azure Key Vault Provider" +linkTitle: "Getting Certificates and Keys using Azure Key Vault Provider" +weight: 6 +description: > + +--- + +> Note: This behavior was introduced in 0.0.6 release of Azure Key Vault Provider for Secrets Store CSI Driver. This is backward incompatible with the prior releases. + +The Azure Key Vault Provider for Secrets Store CSI Driver has been designed to closely align with the current behavior of [az keyvault certificate/secret/key download](https://docs.microsoft.com/en-us/cli/azure/keyvault?view=azure-cli-latest). + +[Azure Key Vault](https://docs.microsoft.com/azure/key-vault/) design makes sharp distinctions between Keys, Secrets and Certificates. The KeyVault service's Certificates features were designed making use of it's Keys and Secrets capabilities. + +> When a Key Vault certificate is created, an addressable key and secret are also created with the same name. The Key Vault key allows key operations and the Key Vault secret allows retrieval of the certificate value as a secret. A Key Vault certificate also contains public x509 certificate metadata. + +The KeyVault service stores both the public and the private parts of your certificate in a KeyVault secret, along with any other secret you might have created in that same KeyVault instance. + +## How to obtain the certificate + +Knowing that the certificate is stored in a Key Vault certificate, we can retrieve it by using object type `cert`. + +> Note: For chain of certificates, using object type `cert` only returns the Server certificate and not the entire chain. + +```yaml + array: + - | + objectName: certName + objectType: cert + objectVersion: "" +``` + +The contents of the file will be the certificate in PEM format. + +## How to obtain the public key + +Knowing that the public key is stored in a Key Vault key, we can retrieve it by using object type `key` + +```yaml + array: + - | + objectName: certName + objectType: key + objectVersion: "" +``` + +The contents of the file will be the public key in PEM format. + +## How to obtain the private key and certificate + +Knowing that the private key is stored in a Key Vault secret with the public certificate included, we can retrieve it by using object type `secret` + +```yaml + array: + - | + objectName: certName + objectType: secret + objectVersion: "" +``` + +The contents of the file will be the private key and certificate in PEM format. + +> Note: For chain of certificates, using object type `secret` returns entire certificate chain along with the private key. diff --git a/website/content/en/configurations/identity-access-modes/_index.md b/website/content/en/configurations/identity-access-modes/_index.md new file mode 100644 index 000000000..4a6c35bbc --- /dev/null +++ b/website/content/en/configurations/identity-access-modes/_index.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "Identity Access Modes" +linkTitle: "Identity Access Modes" +weight: 1 +description: > + The Azure Key Vault Provider offers four modes for accessing a Key Vault instance +--- \ No newline at end of file diff --git a/website/content/en/configurations/identity-access-modes/pod-identity-mode.md b/website/content/en/configurations/identity-access-modes/pod-identity-mode.md new file mode 100644 index 000000000..54f57778c --- /dev/null +++ b/website/content/en/configurations/identity-access-modes/pod-identity-mode.md @@ -0,0 +1,116 @@ +--- +type: docs +title: "Pod Identity" +linkTitle: "Pod Identity" +weight: 2 +description: > + Use Pod Identity +--- + +> Supported only on Linux + +**Prerequisites** + +💡 Make sure you have installed pod identity to your Kubernetes cluster + + __This project makes use of the aad-pod-identity project located [here](https://github.com/Azure/aad-pod-identity#getting-started) to handle the identity management of the pods. Reference the aad-pod-identity README if you need further instructions on any of these steps.__ + +Not all steps need to be followed on the instructions for the aad-pod-identity project as we will also complete some of the steps on our installation here. + +1. Install the aad-pod-identity components to your cluster + + - Install the RBAC enabled aad-pod-identiy infrastructure components: + ``` + kubectl apply -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment-rbac.yaml + ``` + + - 💡 Follow the [Role assignment](https://github.com/Azure/aad-pod-identity/blob/master/docs/readmes/README.role-assignment.md) documentation to setup all the required roles for aad-pod-identity components. + +1. Create an Azure User Identity + + Create an Azure User Identity with the following command. + Get `clientId` and `id` from the output. + ``` + az identity create -g -n + ``` + +1. Assign permissions to new identity + Ensure your Azure user identity has all the required permissions to read the keyvault instance and to access content within your key vault instance. + If not, you can run the following using the Azure cli: + + ```bash + # Assign Reader Role to new Identity for your keyvault + az role assignment create --role Reader --assignee --scope /subscriptions//resourcegroups//providers/Microsoft.KeyVault/vaults/ + + # set policy to access keys in your keyvault + az keyvault set-policy -n $KEYVAULT_NAME --key-permissions get --spn + # set policy to access secrets in your keyvault + az keyvault set-policy -n $KEYVAULT_NAME --secret-permissions get --spn + # set policy to access certs in your keyvault + az keyvault set-policy -n $KEYVAULT_NAME --certificate-permissions get --spn + ``` + +1. Add a new `AzureIdentity` for the new identity to your cluster + + Edit and save this as `aadpodidentity.yaml` + + Set `type: 0` for Managed Service Identity; `type: 1` for Service Principal + In this case, we are using managed service identity, `type: 0`. + Create a new name for the AzureIdentity. + Set `resourceID` to `id` of the Azure User Identity created from the previous step. + + ```yaml + apiVersion: "aadpodidentity.k8s.io/v1" + kind: AzureIdentity + metadata: + name: + spec: + type: 0 + resourceID: /subscriptions//resourcegroups//providers/Microsoft.ManagedIdentity/userAssignedIdentities/ + clientID: + ``` + + ```bash + kubectl create -f aadpodidentity.yaml + ``` + +1. Add a new `AzureIdentityBinding` for the new Azure identity to your cluster + + Edit and save this as `aadpodidentitybinding.yaml` + ```yaml + apiVersion: "aadpodidentity.k8s.io/v1" + kind: AzureIdentityBinding + metadata: + name: + spec: + azureIdentity: + selector: