zuplo 6.67.32 → 6.68.0

package/docs/articles/step-3-add-api-key-auth-local.mdx

@@ -0,0 +1,199 @@
+---
+title: Step 3 - API Key Authentication
+sidebar_label: "3 - API Key Auth"
+---
+
+<QuickstartPicker
+  mode="local"
+  alternateLink="/articles/step-3-add-api-key-auth"
+/>
+
+In this guide we'll add API Key authentication to a route. You can do this for
+any Zuplo project but will need a route, consider completing
+[Step 1](./step-1-setup-basic-gateway-local.mdx) first.
+
+API Key authentication is one of our most popular **policies** as implementing
+this authentication method is considered one of the easiest to use by developers
+but hard for API developers to get right. We also support JWT tokens and most
+other authentication methods.
+
+:::info{title="What's a Policy?"}
+
+[Policies](./policies.mdx) are modules that can intercept and transform an
+incoming request or outgoing response. Zuplo offers a wide range of policies
+built-in (including API key authentication) to save you time. You can check out
+[the full list](./policies.mdx).
+
+:::
+
+Let's get started.
+
+<Stepper>
+
+1.  Link your Local Project
+
+    When developing locally with Zuplo, you can "link" your local project to
+    your Zuplo project using the `zuplo link` command. This allows you to test
+    your changes in a real environment.
+
+    When you run the command you will be prompted to select your Zuplo account,
+    project, and environment. You can pick any environment.
+
+    ```bash
+    npx zuplo link
+    ```
+
+    After your project is linked, environment variables and other configuration
+    from your Zuplo project will be available in your local development
+    environment.
+
+1.  Start your Project
+
+    You can start your project using the following command:
+
+    ```bash
+    npx zuplo dev
+    ```
+
+    After your project is started, you can open the local route designer at
+    http://localhost:9100.
+
+1.  Add the API Key Authentication Policy
+
+    Open the local **Route Designer** by navigating to http://localhost:9100/.
+    Select your route and click **Add Policy** on the incoming request policies
+    section.
+
+    <BrowserScreenshot url="http://localhost:9100/?path=routes.oas.json">
+
+    ![Add Policy](../../public/media/step-3-add-api-key-auth-local/image.png)
+
+    </BrowserScreenshot>
+
+    Search for the API key authentication policy, click on it, and then click
+    **Create Policy** to accept the default policy JSON.
+
+    <ModalScreenshot>
+
+    ![Add API Key Authentication](../../public/media/step-3-add-api-key-auth/choose-policy.png)
+
+    </ModalScreenshot>
+
+    :::tip
+
+    The API key authentication policy should usually be one of the first
+    policies executed. If you came here from
+    [Step 2](./step-2-add-rate-limiting.mdx) then you will want to drag it above
+    the rate limiting policy.
+
+    :::
+
+    ![reorder policies](../../public/media/step-3-add-api-key-auth/image-1.gif)
+
+    If you test your route, you should get a 401 Unauthorized response
+
+    ```json
+    {
+      "status": 401,
+      "title": "Unauthorized",
+      "type": "https://httpproblems.com/http-status/401"
+    }
+    ```
+
+1.  Set up an API Key
+
+    In order to call your API, you need to configure an API consumer. Go to the
+    [Zuplo Portal](https://portal.zuplo.com), then open the project you are
+    working on, **Services**, then click **Configure** on the "API Key Service".
+
+    :::warning
+
+    Be sure to select the appropriate environment in the dropdown on the top
+    right of the services page. You must select the environment type you linked
+    your local project to. If you only have a single environment, you should
+    select "Production". Later we will create new environments for preview.
+
+    :::
+
+    ![API Key Service](../../public/media/step-3-add-api-key-auth/image-2.png)
+
+    Then click **Create Consumer**.
+
+    ![Create Consumer](../../public/media/step-2-add-api-key-auth/image-8.png)
+
+    Let's break down the configuration needed.
+    - Subject: Also known as `sub`. This is a unique identifier of the API
+      consumer. This is commonly the name of the user or organization consuming
+      your API
+    - Key managers: The email addresses of those who will be managing this API
+      key.
+    - Metadata: JSON metadata that will be made available to the runtime when a
+      key is used to authenticate. Common properties include the consumer's
+      subscription plan, organization, etc.
+
+    Go ahead and fill in `test-consumer` for the Subject. Add your own email as
+    a Key manager, and leave the metadata empty for now. Click **Save consumer**
+    once you're done.
+
+    <ModalScreenshot>
+
+    ![New Consumer](../../public/media/step-3-add-api-key-auth/image-3.png)
+
+    </ModalScreenshot>
+
+1.  Copy your API Key
+
+    After your API Key consumer is created, copy your new API Key by clicking
+    the copy button (next to the eye icon).
+
+    ![Copy Key](../../public/media/step-3-add-api-key-auth/image-4.png)
+
+1.  Test out your API Key
+
+    Using any HTTP client (like Postman or curl), make a request to your API.
+
+    ```bash
+    curl --request GET \
+    --url http://localhost:9000/path-1 \
+    --header 'Authorization: Bearer zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx'
+    ```
+
+    You should get a 401 Unauthorized response - as we haven't supplied the API
+    key yet. Add a new `authorization` header with the value
+    `Bearer <YOUR_API_KEY>` and insert the API Key you got from the developer
+    portal.
+
+    You should now get a 200 OK.
+
+    ```json
+    {
+      "url": "https://echo.zuplo.io/path-1",
+      "method": "GET",
+      "query": {},
+      "headers": {
+        "accept": "*/*",
+        "accept-encoding": "gzip, br",
+        "connection": "Keep-Alive",
+        "host": "echo.zuplo.io",
+        "true-client-ip": "12.63.237.42",
+        "user-agent": "curl/8.7.1",
+        "x-forwarded-proto": "https",
+        "x-real-ip": "12.63.237.42",
+        "zp-rid": "ecfac0de-f039-4ced-997c-b17c9babc944"
+      }
+    }
+    ```
+
+    :::note
+
+    We also offer an API for our API key service that allows you to
+    programmatically create consumers and even create your own developer portal
+    or integrate key management into your existing dashboard. See
+    [this document for details](./api-key-api.mdx).
+
+    :::
+
+</Stepper>
+
+**NEXT** Try
+[Step 4 - Connect Source Control and Deploy to the Edge](./step-4-deploying-to-the-edge.mdx).

package/docs/articles/step-3-add-api-key-auth.mdx

@@ -0,0 +1,166 @@
+---
+title: Step 3 - API Key Authentication
+sidebar_label: "3 - API Key Auth"
+---
+
+<QuickstartPicker
+  mode="portal"
+  alternateLink="/articles/step-3-add-api-key-auth-local"
+/>
+
+In this guide we'll add API Key authentication to a route. You can do this for
+any Zuplo project but will need a route, consider completing
+[Step 1](./step-1-setup-basic-gateway.mdx) first.
+
+API Key authentication is one of our most popular **policies** as implementing
+this authentication method is considered one of the easiest to use by developers
+but hard for API developers to get right. We also support JWT tokens and most
+other authentication methods.
+
+:::info{title="What's a Policy?"}
+
+[Policies](./policies.mdx) are modules that can intercept and transform an
+incoming request or outgoing response. Zuplo offers a wide range of policies
+built-in (including API key authentication) to save you time. You can check out
+[the full list](./policies.mdx).
+
+:::
+
+Let's get started.
+
+<Stepper>
+
+1. Add the API Key Authentication Policy
+
+   Navigate to your route in the **Route Designer** (**Code** >
+   `routes.oas.json`) and open the **Policies** section. Then click **Add
+   Policy**.
+
+   ![Add Policy](../../public/media/step-3-add-api-key-auth/image.png)
+
+   Search for the API key authentication policy, click on it, and then click OK
+   to accept the default policy JSON.
+
+   <ModalScreenshot>
+
+   ![Add API Key Authentication](../../public/media/step-3-add-api-key-auth/choose-policy.png)
+
+   </ModalScreenshot>
+
+   :::tip
+
+   The API key authentication policy should usually be one of the first policies
+   executed. If you came here from [Step 2](./step-2-add-rate-limiting.mdx) then
+   you will want to drag it above the rate limiting policy.
+
+   :::
+
+   ![reorder policies](../../public/media/step-3-add-api-key-auth/image-1.gif)
+
+   If you test your route, you should get a 401 Unauthorized response
+
+   ```json
+   {
+     "status": 401,
+     "title": "Unauthorized",
+     "type": "https://httpproblems.com/http-status/401"
+   }
+   ```
+
+2. Set up an API Key
+
+   In order to call your API, you need to configure an API consumer. Go to
+   **Services**, then click **Configure** on the "API Key Service".
+
+   ![API Key Service](../../public/media/step-3-add-api-key-auth/image-2.png)
+
+   Then click **Create Consumer**.
+
+   ![Create Consumer](../../public/media/step-2-add-api-key-auth/image-8.png)
+
+   Let's break down the configuration needed.
+   - Subject: Also known as `sub`. This is a unique identifier of the API
+     consumer. This is commonly the name of the user or organization consuming
+     your API
+   - Key managers: The email addresses of those who will be managing this API
+     key.
+   - Metadata: JSON metadata that will be made available to the runtime when a
+     key is used to authenticate. Common properties include the consumer's
+     subscription plan, organization, etc.
+
+   Go ahead and fill in `test-consumer` for the Subject. Add your own email as a
+   Key manager, and leave the metadata empty for now. Click **Save consumer**
+   once you're done.
+
+   <ModalScreenshot>
+
+   ![New Consumer](../../public/media/step-3-add-api-key-auth/image-3.png)
+
+   </ModalScreenshot>
+
+3. Copy your API Key
+
+   After your API Key consumer is created, copy your new API Key by clicking the
+   copy button (next to the eye icon).
+
+   ![Copy Key](../../public/media/step-3-add-api-key-auth/image-4.png)
+
+4. Test out your API Key
+
+   Navigate back to the **Route Designer**, and select your route. Next to the
+   path of your route, click the **Test** button and fire off a request.
+
+   <ModalScreenshot>
+
+   ![Failed unauthorized error](../../public/media/step-3-add-api-key-auth/test-policy.png)
+
+   </ModalScreenshot>
+
+   You should get a 401 Unauthorized response - as we haven't supplied the API
+   key yet. Add a new `authorization` header with the value
+   `Bearer <YOUR_API_KEY>` and insert the API Key you got from the developer
+   portal.
+
+   You should now get a 200 OK.
+
+   <ModalScreenshot>
+
+   ![successful response](../../public/media/step-3-add-api-key-auth/image-6.png)
+
+   </ModalScreenshot>
+
+   :::note
+
+   We also offer an API for our API key service that allows you to
+   programmatically create consumers and even create your own developer portal
+   or integrate key management into your existing dashboard. See
+   [this document for details](./api-key-api.mdx).
+
+   :::
+
+5. View your API Documentation
+
+   Whenever you deploy a new endpoint on Zuplo, it will automatically be added
+   to your
+   [autogenerated developer documentation portal](../dev-portal/introduction.mdx).
+
+   To access your API's developer portal, click the **Gateway deployed** button
+   in your toolbar and click the link under Developer Portal.
+   ![Developer portal menu](../../public/media/step-2-add-rate-limiting/image-5.png)
+
+   When you use certain policies like API keys, Zuplo will document properties
+   like headers associated with that policy. As you can see on the right, the
+   API key policy's `Authorization` header has been documented for you.
+
+   ![Developer Portal Endpoint](../../public/media/step-3-add-api-key-auth/image-7.png)
+
+   Additionally, a new Authentication section has been added to your developer
+   portal. Users of your API can sign in, view & manage their API keys, test
+   your endpoints, track API usage, and much more! You can learn more about that
+   in
+   [our developer portal auth docs](/docs/dev-portal/zudoku/configuration/authentication).
+
+</Stepper>
+
+**NEXT** Try
+[Step 4 - Connect Source Control and Deploy to the Edge](./step-4-deploying-to-the-edge.mdx).

package/docs/articles/step-4-deploying-to-the-edge.mdx

@@ -0,0 +1,220 @@
+---
+title: Step 4 - Deploying to the Edge
+sidebar_label: "4 - Deploy"
+---
+
+In this guide we'll show you how to deploy your gateway to the edge, at over 300
+data-centers around the world. The act of deployment creates new
+[environments](./environments.mdx) and it's worth familiarizing yourself with
+[how environments work](./environments.mdx).
+
+In this tutorial we'll show the default workflow via GitHub, but note that we
+also support GitLab, BitBucket
+([enterprise plan only](https://zuplo.com/pricing)) and
+[custom CI/CD](./custom-ci-cd.mdx).
+
+To follow this tutorial you'll need
+
+- a GitHub account (it's free, sign up at [github.com](https://github.com)).
+- a zuplo project - complete [Step 1](./step-1-setup-basic-gateway.mdx),
+  [Step 2](./step-2-add-rate-limiting.mdx) and
+  [Step 3](./step-3-add-api-key-auth.mdx) for a great start!
+- to install the
+  [Zuplo GitHub deployment](https://github.com/apps/zuplo/installations/new) to
+  GitHub - you can
+  [follow these instructions](https://github.com/apps/zuplo/installations/new)
+
+Let's get started:
+
+<Stepper>
+
+1. Authorize to GitHub
+
+   Next, go to your project in the Zuplo portal, click **Settings**, then select
+   **Source Control**. If your project isn't already connected to GitHub click
+   the **Connect to GitHub** button and follow the auth flow. You'll need to
+   grant permissions for any GitHub organizations you want to work with.
+
+   ![Connect GitHub](../../public/media/step-4-deploying-to-the-edge/image-1.png)
+
+   Next, a dialog will open asking you to authorize Zuplo. Click the **Authorize
+   Zuplo** button.
+
+   <Framed size="sm">
+
+   ![Zuplo GitHub connection](../../public/media/step-4-deploying-to-the-edge/d6194a80-b6d6-429e-85a6-ae1cb4a3375e.png)
+
+   </Framed>
+
+   <Callout type="tip" title="GitHub Permissions" >
+
+   The permission "Act on your behalf" sounds a bit scary - however, this is a
+   standard GitHub permission and by default Zuplo can't actually do anything
+   with this. In order to perform actions on your behalf you must grant Zuplo
+   access to a specific repository (shown in the next steps.).
+
+   [read more about this permission on GitHub's docs](https://docs.github.com/en/apps/using-github-apps/authorizing-github-apps#about-github-apps-acting-on-your-behalf).
+
+   </Callout>
+
+   After you have connected the GitHub app, it needs to be granted permission to
+   edit a repository. If this is your first time connecting Zuplo, you will be
+   immediately asked to select a GitHub Org to install Zuplo. Select the org you
+   want to use.
+
+   <Framed size="sm">
+
+   ![Installing Zuplo app](../../public/media/step-4-deploying-to-the-edge/eef76bd7-4d26-4f86-96e8-89ebede03beb.png)
+
+   </Framed>
+
+   Next, you will be asked to select the repositories that you want Zuplo to
+   access. The easiest thing is to just select **All Repositories**, but if you
+   want fine-grain control, you can select a specific repository.
+
+   <Framed size="sm">
+
+   ![Choosing repository to install](../../public/media/step-4-deploying-to-the-edge/ff482269-9aa2-44c3-8266-b2682b3d6ea5.png)
+
+   </Framed>
+
+   <Callout type="caution" title="Existing Installation" >
+
+   The next step is only if you already have Zuplo installed in a GitHub org and
+   need to add another organization.
+
+   </Callout>
+
+   If you weren't prompted to select a GitHub org, it's likely that you are
+   already a member of an account that has authorized Zuplo. To add Zuplo to a
+   new organization click **Add GitHub Account** in the org picker list.
+
+   ![Connect Org](../../public/media/step-4-deploying-to-the-edge/image-2.png)
+
+1. Connect GitHub to your Project
+
+   With your GitHub App configured, you can now return to the Zuplo portal. In
+   the **Source Control** settings you should now see a list of GitHub
+   repositories. Create a new repository by clicking the **Create new
+   repository** button. You will be prompted that this will open GitHub. Click
+   to continue.
+
+   ![Create Repository](../../public/media/step-4-deploying-to-the-edge/image-3.png)
+
+   In the GitHub UI, you can rename your repository if you want. Click the
+   **Create repository** button at the bottom of the page and return to the
+   Zuplo Portal.
+
+   The portal will reload and you will see your new repository listed. Click
+   **Connect** to connect Zuplo to that repository.
+
+   ![Connect](../../public/media/step-4-deploying-to-the-edge/image-4.png)
+
+   After the connection succeeds you will see a link to your GitHub repository.
+
+   ![Connected Repository](../../public/media/step-4-deploying-to-the-edge/image-5.png)
+
+   Click the link to return to GitHub. You should see a little brown dot next to
+   the commit hash (1). When you hover your mouse over that you'll see the Zuplo
+   deployment was successful. Click **Details** (2) to open the deployment info.
+
+   This shows that your deployment is in progress, it will take about 50
+   seconds.
+
+   ![Zuplo deployment run](../../public/media/step-4-deploying-to-the-edge/brown-dot.png)
+
+   On the deployment page, you will see **Deployment has Completed!!** and below
+   that's the link to your new environment.
+
+   ![Zuplo deployment run result](../../public/media/step-4-deploying-to-the-edge/26fa58b6-7a5a-4627-bd9f-246972639f12.png)
+
+1. Deploy another Environment
+
+   Zuplo makes it easy for teams to collaborate by allowing teams to create many
+   preview environments. To create a new environment, simply go to your
+   repository in GitHub and create a new branch.
+
+   Let's create a branch called `development`
+
+   ![Create new branch](../../public/media/step-4-deploying-to-the-edge/60cdeb36-ab7d-42f9-a8c2-1f7931f80ca6.png)
+
+   Wait about 20s and head back to Zuplo - you should see a new entry in the
+   environment dropdown called `development`.
+
+1. Push a Change to 'development'
+
+   Let's make a simple change to our `working-copy` environment. Let's do
+   something simple like capitalize the **Summary** field from 'Get all todos'
+   to 'Get All Todos'. It doesn't really matter what the change is.
+
+   ![Changes Summary](../../public/media/step-4-deploying-to-the-edge/image-6.png)
+
+   Save your changes. Click the GitHub button at bottom left and choose **Commit
+   & Push**.
+
+   ![Commit & Push](../../public/media/step-4-deploying-to-the-edge/image-7.png)
+
+   Enter a description of your change in the dialog that pops up:
+
+   <ModalScreenshot>
+
+   ![Change Summary](../../public/media/step-4-deploying-to-the-edge/image-8.png)
+
+   </ModalScreenshot>
+
+   Click **Commit & Push** will create a new temporary branch in GitHub with a
+   name `zup-...`. On the next dialog, click **Create Pull Request**.
+
+   <ModalScreenshot>
+
+   ![Create PR](../../public/media/step-4-deploying-to-the-edge/image-9.png)
+
+   </ModalScreenshot>
+
+   This will navigate you to the screen in GitHub that allows you to create a
+   Pull Request. Change the **base** branch to `development` (since that's the
+   environment we want to update first). Click **Create pull request**.
+
+   ![GitHub PR](../../public/media/step-4-deploying-to-the-edge/875b164d-b7ef-4f46-9cdb-8d59354b5b93.png)
+
+   When ready, click **Merge pull request**.
+
+   ![Merge PR](../../public/media/step-4-deploying-to-the-edge/e8c68072-35dc-462a-8161-7a44e40fa1df.png)
+
+   Once merged, you'll want to delete that temporary branch.
+
+   ![Delete branch](../../public/media/step-4-deploying-to-the-edge/51a25aa0-cdce-4112-ba2e-e56f42a9044d.png)
+
+   The successful merge will trigger a rebuild and deployment of `development`
+   with your change. You can check this by choosing the environment
+   `development` in Zuplo and navigating to the **read only** Route Designer.
+
+   ![Navigating Environments](../../public/media/step-4-deploying-to-the-edge/image.png)
+
+   This shows how you can use widely recognized GitOps practices to manage how
+   code flows through your environments using Pull Requests and protected
+   branches.
+
+</Stepper>
+
+## Troubleshooting
+
+I don't see my repository listed in Zuplo project settings.
+
+- Make sure you've granted access to the project with the Zuplo GitHub App, you
+  can
+  [check that configuration here](https://github.com/apps/zuplo/installations/new)
+
+I've connected my Zuplo project to a GitHub repository but get access errors
+when running commits, pulls or try to open a pull request.
+
+- If you are the owner of the project, make sure you've granted access to the
+  project with the Zuplo GitHub App, you can
+  [check that configuration here](https://github.com/apps/zuplo/installations/new)
+- If this Zuplo project was shared with you, make sure you are a GitHub
+  collaborator. This can be verified by going to the GitHub repository >
+  Settings > Collaborators section. You'll need admin permissions to the
+  repository.
+- If the GitHub repository has been renamed or moved to a different
+  organization, try disconnecting and reconnecting to it. You can do this by
+  going to your Zuplo project's settings > Source Control section