Live AWS Documentation In Confluence With Cloudviz API

What is Cloudviz API?

The Cloudviz.io API provides an easy way to generate live diagrams (SVG, PNG, PDF or Draw.io / Diagrams.net.) or complete JSON snapshot of your AWS account with one API request.

Here are few options to kick start your Cloudviz API usage:

• Cloudviz API Postman Collection
• Open API Specification

Keep Up-to-Date Documentation in Confluence

By having documentation in Confluence you have all your cloud environment details in one place nicely organized and you don't have to browse through multiple AWS services in AWS console, switch the accounts to find the necessary details about your deployed services.

• For development teams it helps to quickly onboard new employees to get the full picture of cloud environments.
• For managed cloud services providers and consulting agencies it helps to have documentation for all their clients in one place and keep it automatically up-to-date. With an easy way to see the full picture of cloud environments results to better service for their clients and less time spent on documentation.

The advantage of using Cloduviz API for customized documentation approach is not only the endless possibilities for implementing tailored documentation that aligns with your organization's specific needs but also the ability to avoid sharing your Confluence, Teams, Slack, etc., credentials with third parties, thereby reducing the potential for credential compromise.

Let's explore just few capabilities of the Cloudviz.io API to keep up-to-date documentation in Confluence.

In order to showcase few usage scenarios we have developed functional service confluence-live-documentation for generating AWS documentation based on live data from your AWS environments and updating Confluence.

We will go more in details for following scenarios:

• Schedule Automated Diagram Generation
• Text Data For Generated Diagrams
• Document Specific Application
• Document Multiple AWS Accounts / Regions

Schedule Automated Diagram Generation

To schedule automated diagram and documentation generation we will use:

• Cloudviz.io API to automatically generate diagram
• AWS Lambda and EventBridge rule to trigger and process diagram generation
• Confluence Cloud REST API to push generated diagrams to Confluence page
• Serverless Framework for easy deployment to AWS

Confluence Config

Before we can start to schedule diagram and documentation updates in Confluence, we have to create new Confluence space (or use existing one) where the generated documentation will be stored and get the space id. Quick way to get the space id is to use this link: https://YOUR_CONFLUENCE_URL.atlassian.net/wiki/rest/api/space/YOUR_SPACE_NAME.

We also have to crete Confluence API Token to authenticate the API requests to update generated documentation.

Following Confluence API's will be used:

• GET /wiki/api/v2/spaces/SPACE_ID/pages to get details of all the pages in the specific Confluence space
• PUT /wiki/rest/api/content/PAGE_ID/child/attachment to upload an attachment (diagram) to a Confluence page
• PUT /wiki/api/v2/pages/PAGE_ID to update specific Confluence page
• POST /wiki/api/v2/pages to create specific Confluence page

Diagram Generation Using AWS Lambda

We will use AWS Lambda function (Node.js 18.x as our Lambda function runtime) to generate diagrams using Cloudviz.io API. And will use default Node.js fetch API to make API calls to Cloudviz.io API and Confluence API.

Following Cloudviz API's will be used:

• GET /aws/accounts to get a list of available connceted AWS accounts
• GET /aws/accounts/ACCOUNT_ID/REGION/FORMAT to generate diagrams and JSON snapshot

In order to authenticate Cloudviz API requests API key should be provided in the header. Create one in the Cloudviz.io app section Manage API Keys -> Create API Key.

Here is Lambda handler code which will be triggered by scheduled Eventbridge event:

import {
  generateAndUpdateDocumentation,
  getSecretFromParameterStore,
} from './documentation-helpers.mjs';

/**
 * Lambda handler to update Confluence page with Cloudviz diagrams and text data.
 * To be triggered by scheduled event (see serverless.yml)
 */
export const handler = async (event) => {
  // read configuration values config from AWS System Manager Parameter Store
  const cloudvizConfig = JSON.parse(await getSecretFromParameterStore('CLOUDVIZ_CONFIG'));
  const confluenceConfig = JSON.parse(await getSecretFromParameterStore('CONFLUENCE_CONFIG'));

  await generateAndUpdateDocumentation(confluenceConfig, cloudvizConfig);
};

All the rest of the code is available in our GitHub repository cloudviz-api-usage-samples

Create Configuration Parameters

Before we deploy our documentation service to AWS we have to create two configuration parameters (as SecureString) in AWS Systems Manager Parameter Store:

• CLOUDVIZ_CONFIG
  
  {
    "cloudvizApiKey": "<your-cloudviz-api-key>",
    "documentationConfig": [
      {
        "accountId": "123456-1234-1234-1234-1234567",
        "region": "eu-west-1",
        "format": "svg",
        "queryString": "",
        "addTextData": true,
        "showTableOfContents": true
      }
    ]
  }

• CONFLUENCE_CONFIG
  
  {
      "confluenceSpaceId": "123456",
      "confluenceUrl": "https://<your-confluence-name>.atlassian.net",
      "confluenceApiToken": "<confluence-api-key>",
      "confluenceUserName": "your@email.com" 
  }

Read more details about these configuration parameters in our GitHub repository: confluence-live-documentation

Deployment to AWS

In order to deploy our Lambda and schedule automated documentation generation and updates we will use Serverless Framework. It's super easy to use it. To deploy all the necessary services in AWS we only need few lines of yml config file:

service: confluence-documentation

# exclude all the files/folders by default and include individually in the functions
package:
  individually: true
  patterns:
    - '!./**'

provider:
  name: aws
  runtime: nodejs18.x
  stage: ${opt:stage, 'dev'}
  region: ${opt:region, 'eu-west-1'}
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - ssm:GetParameter
          Resource:
            - arn:aws:ssm:${self:provider.region}:*:parameter/CLOUDVIZ_CONFIG
            - arn:aws:ssm:${self:provider.region}:*:parameter/CONFLUENCE_CONFIG

functions:
  update-documentation:
    handler: src/documentation-handler.handler
    timeout: 600 # for large AWS accounts, you might need to increase this value
    memorySize: 1024
    events:
      - schedule: cron(0 0 * * ? *) # generate new documentation every day at midnight
    package:
      patterns:
        - src/**

With the simple command like npm run deploy --stage dev region=eu-west-1 you can deploy this service to any AWS account / region

Read more about deployment steps here: confluence-live-documentation

Live Diagrams in Confluence

After we have deployed our documentation service to AWS we can trigger Lambda to generate and update documentation in Confluence. In this example we generated only diagrams for five AWS regions / applications that we configuered in CLOUDVIZ_CONFIG documentationConfig parameter.

Text Data For Generated Diagrams

In previous example we generated only diagrams for five AWS regions / applications. Now let's generate diagrams with text data and update Confluence.

Our confluence-live-documentation service already supports adding text data so the only thing that we have to do is to set addTextData to true in CLOUDVIZ_CONFIG documentationConfig parameter:

{
  "cloudvizApiKey": "your-cloudviz-api-key",
  "documentationConfig": [
    {
      "accountId": "9f91s600-5c5a-11ee-b12d-57664c9998b0",
      "region": "eu-west-1",
      "format": "svg",
      "queryString": "",
      "addTextData": true,
      "showTableOfContents": true
    },
    {
      "accountId": "9f91s600-5c5a-11ee-b12d-57664c9998b0",
      "region": "eu-north-1",
      "format": "svg",
      "queryString": "",
      "addTextData": true,
      "showTableOfContents": true
    },
    {
      "accountId": "9f91s600-5c5a-11ee-b12d-57664c9998b0",
      "region": "us-east-1",
      "format": "svg",
      "queryString": "",
      "addTextData": false,
      "showTableOfContents": true
    },
    {
      "accountId": "9f91s600-5c5a-11ee-b12d-57664c9998b0",
      "region": "eu-west-1",
      "format": "svg",
      "queryString": "filter=vpc-089297763ae94c2ab",
      "customPageTitle": "On premise connection VPC",
      "addTextData": false,
      "showTableOfContents": true
    },
    {
      "accountId": "64afgha20-6953-11eb-8579-41617efaf779",
      "region": "eu-west-1",
      "format": "svg",
      "queryString": "",
      "addTextData": true,
      "showTableOfContents": true
    }
  ]
}

As you will see in the video below that we can easily document not only multiple AWS acocunts and regions but specific application / subset (ex. "On premise connection VPC") of your AWS environment.

Automated Document Generation via Cloudviz App

If you prefer not to integrate with Confluence and simply wish to create Word documents, the Cloudviz app is your ideal solution. It allows you to effortlessly generate Word documents containing diagrams and textual information for all your AWS environments.Read here more in details about generating AWS documentation.

You can schedule autogeneration of your documentation for your AWS environments by creating automation profiles. Cloudviz.io will do all the hard work so you don't have to spend time on refreshing and maintaining actual documentation of your AWS infrastructure. The cool thing is that you can set specific visualization settings for your AWS environment as generation settings profile and create automation profile to use these settings when generating the documentation. For more details read our FAQ section

Start your free trial