feat: akamai integration

docs/cloud/akamai.mdx

@@ -0,0 +1,296 @@
+---
+title: 'Configure Akamai on Zephyr'
+description: 'Configuring Akamai as your deployment integration provider on Zephyr'
+---
+
+import { Steps } from '@theme';
+import { Button } from '../../components/ui/button.tsx';
+
+# Configure Akamai on Zephyr
+
+We now support Akamai as a cloud provider for Bring Your Own Cloud (BYOC) deployments. Akamai is a cloud platform known for its global content delivery network (CDN), edge computing capabilities, and strong focus on performance and security. Their infrastructure is designed to help organizations build and scale applications closer to end users while maintaining high availability and low latency.
+
+With this integration, you can leverage your existing Akamai infrastructure to run and manage services directly within your own cloud environment, giving you more control, flexibility, and compliance alignment.
+
+## Prerequisites
+
+:::info
+
+- A registered Akamai account, contract must include edge workers and edgekv
+- A registered Zephyr account
+- A registered domain
+
+:::
+
+## Configure and enable Akamai
+
+<Steps>
+### Log in to the Zephyr Dashboard
+<a href="https://app.zephyr-cloud.io">
+<Button variant="outline" className="hover:bg-zinc-100 hover:text-black">Dashboard</Button>
+</a>
+After signing in, select your organization.
+<br/>
+
+### Locate Akamai under Deployment Integration
+
+- Select **Settings** from the top navigation tabs.
+- On the left sidebar, select **Deployment Integration**.
+- Choose **Available** to find Akamai, then click on **Add integration**.
+
+### Retrieve Credentials and Configure Akamai
+
+Before proceeding, you will need some data from Akamai:
+
+#### 1. API Token
+
+- Click on **Identity and access** in the menu
+- Click on **Create API client**
+- Choose **Advanced**
+- Configure required permissions and remove the rest:
+
+| API                               | Access Level |
+| :-------------------------------- | :----------: |
+| CPcode and Reporting group (cprg) | READ-WRITE   |
+| Edge Hostnames API (hapi)         | READ-WRITE   |
+| EdgeKV                            | READ-WRITE   |
+| EdgeWorkers                       | READ-WRITE   |
+| Property Manager (PAPI)           | READ-WRITE   |
+
+- Copy or download token and add `[default]` as a header, so token will look like:
+
+:::warning Secure Your Credentials
+Keep your API token secure. Never commit credentials to version control or share them publicly.
+:::
+
+```
+[default]
+client_secret = YOUR_CLIENT_SECRET
+host = YOUR_AKAMAI_HOST
+access_token = YOUR_ACCESS_TOKEN
+client_token = YOUR_CLIENT_TOKEN
+```
+
+#### 2. Contract id
+
+- Click on **Contracts** in the menu
+- Find your contract id
+
+#### 3. Group id
+
+- Click on **Properties** in the menu
+- Numeric value in the url is your group id `https://control.akamai.com/apps/property-manager/#/groups/<groupId>/properties`
+
+#### 4. Product id
+
+Find you product [here](https://techdocs.akamai.com/property-mgr/reference/id-prefixes#common-product-ids) and choose product id - **prd_Fresca** or **prd_SPM**
+
+
+### Configuration Inputs
+
+Details for each input after clicking **Add Integration** under **Akamai**:
+
+<dt>Integration Name</dt>
+<dd>
+  A unique name within your organization, used as a slug.
+</dd>
+
+<dt>Integration Display Name</dt>
+<dd>
+  The name of the integration shown on the dashboard.
+</dd>
+
+<dt>API Token</dt>
+<dd>
+  Obtainable from Akamai. [See instructions](#1-api-token) for creating your API token.
+</dd>
+
+<dt>Domain</dt>
+<dd>
+  Your domain.
+</dd>
+
+<dt>Akamai contract id</dt>
+<dd>
+  Obtainable from Akamai. [See instructions](#2-contract-id) for getting your contract id.
+</dd>
+
+<dt>Akamai group id</dt>
+<dd>
+  Obtainable from Akamai. [See instructions](#3-group-id) for getting your group id.
+</dd>
+
+<dt>Akamai product id</dt>
+<dd>
+  Obtainable from Akamai. [See instructions](#4-product-id) for getting your product id.
+</dd>
+
+<dt>Set Integration as Default</dt>
+<dd>
+  When set as default, all Zephyr deployments will use this integration until a
+  new one (default integration) is set. Deployment using integration won't work until Akamai worker and property become activated.
+</dd>
+
+### Validate domain and setup DNS
+
+- Click on **Properties** in the menu
+- Click on your property
+- Click on active version
+- Go to section **Property hostnames**
+- Click on **...** in **Actions** column near any hostname, click **Validate certificate domain** and copy **CNAME Record** value
+- Go to your domain provider (e.g., GoDaddy)
+- Add some CNAME records
+
+  | Subdomain                         | Type  | Value                                      |
+  |-----------------------------------|-------|--------------------------------------------|
+  | _acme-challenge.ze.yourdomain.com | CNAME | < value from verification record >         |
+  | ze.yourdomain.com                 | CNAME | ze.yourdomain.com.edgesuite.net.           |
+  | *.ze.yourdomain.com               | CNAME | ze.yourdomain.com.edgesuite.net.           |
+
+### Wait until worker and property become activated
+
+It may take up to 30 minutes.
+
+</Steps>
+
+### What Will Be Created on Your Akamai Account?
+
+When Akamai is added as your provider on Zephyr, these properties will be created on your Akamai account:
+
+#### 1. EdgeKV Namespace
+
+- `ze-yourdomain-com`
+
+#### 2. EdgeKV access token
+
+- `ekv-token-ze-yourdomain-com`
+
+#### 3. Workers
+
+- `ze.yourdomain.com` (for uploading and serving assets)
+
+#### 4. Property
+
+- `ze.yourdomain.com`
+
+## Clean Uninstall and Reset
+
+:::danger Warning
+
+- Zephyr Cloud does not manage deletion of API tokens or any Akamai account properties.
+- Assets and information on your Akamai account are immutable by default. During a **clean uninstall**, previously deployed assets and information are unrecoverable.
+
+:::
+
+To delete an existing Akamai integration, follow these steps:
+
+### Deactivate property
+
+1. Click on **Properties** in the menu
+2. Click on your property
+3. Click on three **...** in the **Actions** column in the active version line
+4. Choose **Deactivate Production**
+5. Wait until property become deactivated
+6. Go back to properties list
+7. Click on three **...** in the **Actions** column in the your property line
+8. Choose **Delete Property**
+
+### Deactivate worker
+
+1. Click on **EdgeWorkers** in the menu
+2. Click on your worker
+3. Click on three **...** in the **Actions** column in the active version line
+4. Choose **Deactivate version**
+5. Wait until version become deactivated
+6. Go back to workers list
+7. Click on three **...** in the **Actions** column in the your worker line
+8. Choose **Delete EdgeWorker ID**
+
+### Remove edge hostname
+
+1. Click on **Edge Hostnames** in the menu
+2. Click on three **...** in the **Actions** column in the active version line
+3. Choose **Delete Edge Hostname**
+
+### Remove EdgeKV namespace
+
+Can be done only with [Akamai API](https://techdocs.akamai.com/edgekv/reference/delete-namespace).
+
+```javascript filename="Example"
+const EdgeGrid = require('akamai-edgegrid');
+
+const { homedir } = require('node:os');
+const { promisify } = require('node:util');
+
+const edgercPath = homedir() + '/.edgerc';
+const edgercSection = 'default';
+const eg = new EdgeGrid({
+path: edgercPath,
+  section: edgercSection,
+});
+
+const namespaceId = process.env.NAMESPACE;
+const network = process.env.NETWORK || 'production'; // staging or production
+
+eg.auth({
+  path: `/edgekv/v1/networks/${network}/namespaces/${namespaceId}`,
+    method: 'DELETE',
+    headers: {
+    'Content-Type': 'application/json',
+      Accept: 'application/json',
+  },
+  body: {},
+});
+
+const send = promisify(eg.send.bind(eg));
+  send()
+  .then(({ data }) => {
+    console.log('Namespace deleting result', data);
+  })
+  .catch((error) => {
+    console.error('Namespace deleting error', error);
+    process.exit(1);
+  });
+
+```
+
+### Revoke EdgeKV access token
+
+Can be done with [Akamai CLI](https://github.com/akamai/cli-edgeworkers/blob/master/docs/edgekv_cli.md#revoke-access-token) or [Akamai API](https://techdocs.akamai.com/edgekv/reference/delete-token).
+
+```javascript filename="Example"
+const EdgeGrid = require('akamai-edgegrid');
+
+const { homedir } = require('node:os');
+const { promisify } = require('node:util');
+
+const edgercPath = homedir() + '/.edgerc';
+const edgercSection = 'default';
+const eg = new EdgeGrid({
+path: edgercPath,
+  section: edgercSection,
+});
+
+const tokenName = process.env.TOKEN_NAME;
+
+eg.auth({
+  path: `/edgekv/v1/tokens/${tokenName}`,
+    method: 'DELETE',
+    headers: {
+    'Content-Type': 'application/json',
+      Accept: 'application/json',
+  },
+  body: {},
+});
+
+const send = promisify(eg.send.bind(eg));
+send()
+  .then(({ data }) => {
+    console.log('Token revoking result', data);
+  })
+  .catch((error) => {
+    console.error('Token revoking error', error);
+    process.exit(1);
+  });
+
+```

rspress.config.ts

@@ -160,6 +160,10 @@ const sidebar: Sidebar = {
       text: "Cloud Providers",
       link: "/cloud",
       items: [
+        {
+          text: "Akamai",
+          link: "/cloud/akamai",
+        },
         {
           text: "Cloudflare",
           link: "/cloud/cloudflare",