Skip to content

Latest commit

 

History

History
482 lines (322 loc) · 18.7 KB

RUNBOOK.md

File metadata and controls

482 lines (322 loc) · 18.7 KB

Runbook

This document covers operational and administrative information for the application, and should be used to understand how the system is configured and functions, including how to perform deployments, updates, and incident responses.

NOTE! This is a template runbook, and as such you will have to adapt it to your application needs.

Links

Quick access to essential resources and communication channels related to the application's development and operation.

See resources section for overview of all resources used by the application.

Overview Platforms

Quick overview of all platforms used.

Prerequisites

List of all necessary permissions, or knowledge required to perform the tasks described in this runbook.

Permissions required
Competence required

Architecture Diagrams

We are using C4 model for showing architecture diagrams.

Level 1 - System Context diagram

Provides a high-level overview of the system, including its purpose, main components, and how these components interact.

C4Context
title TODO app - System Context Diagram

Person(User, "User", "A user that wants to add and view their TODOs.")

System(Application, "TODO app", "A web application tool that allow users to add and view their TODOs.")
System_Ext(AuthServer, "Oauth2 Authorization Server", "Provides authentication and provides userid and roles for access control")

Rel(User, Application, "Adds and views their TODOs")
Rel(Application, AuthServer, "Uses")

UpdateLayoutConfig($c4ShapeInRow="1", $c4BoundaryInRow="1")
Loading
Level 2 - Container diagram

Provide an overview of the containers (runnable and deployable units) that executes code or stores data.

C4Container
title TODO app - Container Diagram

Person(User, "User", "A user that wants to add and view their TODOs.")

System_Boundary(Application, "TODO app", "Allow users to add and view their TODOs.") {
    Container(WebApp, "Single-Page App", "Typescript & React", "Enables user interaction with the TODO application through a web browser interface.")
    Container(Nginx, "Web Server/Reverse Proxy", "Nginx", "Serves the Single-Page App and acts as a reverse proxy for API requests.")
    Container(API, "API", "Python & FastAPI", "Handles business logic, processes API requests, and provides data to the SPA.")
    ContainerDb(DB, "Database", "mongodb", "Stores data for the TODO application.")
}

Rel(User, WebApp, "Adds and views their TODOs", "HTTPS")
Rel(WebApp, Nginx, "Make API calls to", "HTTPS")
%%Rel(Nginx, WebApp, "Delivers", "HTTPS")
Rel(Nginx, API, "Proxies API calls", "HTTPS")
Rel(API, DB, "Reads from and writes to")

UpdateLayoutConfig($c4ShapeInRow="1", $c4BoundaryInRow="1")
Loading
Authentication flow

The application uses the Authorization Code Grant Flow, with Proof Key for Code Exchange flow. It's a flow that enables a user of a Single-Page Application to safely log in, consent to permissions and fetch an access token in the JWT format. When the user calls the APIs, the access token is attached to the header as a Bearer token. This is the token the API will validate.

sequenceDiagram;
    participant C as Client
    participant O as Resource Owner
    participant A as Authorization Server
    participant R as Resource Server

    C->>O: requests authorization
    O->>C: receives authorization grant
    C->>A: requests access token, presents grant
    A->>C: authenticates client, validates grant, issues access token
    C->>R: requests protected resource, presents access token
    R->>C: validates access token, serves request
Loading
Deployment diagram

Shows how the containers are deployed on the infrastructure.

C4Deployment
title TODO app - Deployment Diagram

Person(User, "User", "A user that wants to add and view their TODOs.")

Deployment_Node(web_browser, "Web Browser", "Browser") {
    Container(spa, "Single-Page App", "Typescript & React", "Enables user interaction with the TODO application through a web browser interface.")
}

Deployment_Node(radix, "Radix", "PaaS") {
    Container(nginx, "Web Server/Reverse Proxy", "Nginx", "Serves the Single-Page App and acts as a reverse proxy for API requests.")
    Container(api, "API", "Python & FastAPI", "Handles business logic, processes API requests, and provides data to the SPA.")
}

Deployment_Node(azure, "Azure", "Cloud") {
  Deployment_Node(azure_sql, "Azure SQL", "PaaS") {
      ContainerDb(db, "Database", "SQL Database", "Stores data for the TODO application.")
  }
}

Rel(User, spa, "Adds and views their TODOs", "HTTPS")
Rel_L(spa, nginx, "Make API calls to", "HTTPS")
%%Rel(nginx, spa, "Delivers", "HTTPS")
Rel(nginx, api, "Proxies API calls", "HTTPS")
Rel(api, db, "Reads from and writes to")

UpdateLayoutConfig($c4ShapeInRow="1", $c4BoundaryInRow="1")
Loading

Resources

List of all resources used by the application, including servers, databases, and cloud services.

Radix

Hosted applications

Name Description
Radix Application The application registered in Radix.
On-prem

Servers

Server User Resource
- - -
Azure

Subscriptions

Subscription Description Group
Azure subscription All Azure resources are located under this subscription.

App registrations

Name Description
App registration The application object registered in Azure for this application.

To make sure that the app registration are compliant:

  • Add additional owner (to the Enterprise Application)
  • Go to the Branding & Properties section and update the Service Management Reference to contain the App ID of the configuration item.

In order for the application to be able to authenticate users, you need an Application Registration in Azure AD that can sign in users and issue tokens.

Secrets, Certificates and Keys

Overview of all secrets and certificates used in the application.

All secrets and certificates are stored inside the Azure Key Vault.

Application secrets

This table shows the secrets that must be populated in the KeyVault for every environment.

Name Description Used by
MONGODB_PASSWORD For authenticating to mongoDB API
SECRET_KEY For signing JWT API

Other secrets

This table shows other secrets not directly used by the application.

Secret Type Description Created by Used by
Federated Credentials Allows GitHub to deploy to Radix Application registration GitHub Repository

Certificates

Certificate Name Description
- -

Keys

Type Description Created by Used by
Deployment Key Allows Radix to clone GitHub repository Radix Application GitHub Repository

Administrative Tasks

Higher-level tasks associated with managing and configuring the system.

Environments and Resources Management

Updating system configuration files. Deploying new versions or patches.

Radix Environments

Describe how to configure and deploy Radix environments.

Configurations of Radix environments can be adjusted by modifying the radixconfig.yaml file in the GitHub repository.

Outlined below are descriptions of each environment with their respective deployment strategies.

Environment Deployed how?
Development Automatically deployed from every commit to the main branch on GitHub
Testing Deployment is manually triggered by merging a pull-request generated from release-please
Production Promoted manually via the Radix web console from the Testing environment

How to deploy to development environment:

  1. Create a pull request to main branch and assert that all checks passes.
  2. Merge the pull request and follow conventional commits for commit message.
  3. The development environment in Radix will now be built and deployed automatically.

How to deploy to testing environment:

  1. The release-please GitHub action runs on every commit to main, generating a changelog, and proposing a new version bump in a pull-request to main branch.
  2. Merging the release-please pull request will trigger release-please to run once again and it will detect that there has been a new release.
  3. The testing environment in Radix will now be built and deployed automatically.

How to promote testing to production environment:

  1. Go to the Radix web console and promote the application from the Testing environment to the Production environment.

Azure Resources

Describe how to configure and deploy Azure resources.

Azure resources are defined using Bicep, and configuration can be adjusted by modifying the *.bicep files located under the IaC/ folder.

Bicep files (found under the IaC/ folder):

  • The main.bicep file creates the resource group (dev, staging, or prod) and calls the resources.bicep file to create the resources (key vault, database, app insights, etc.).

  • The app-registration.bicep file creates the app registration used for the application.

  • How to test the bicep files:

az bicep build --file ./<FILENAME>.bicep --stdout

az deployment group create --resource-group <RESOURCE-GROUP-NAME> --template-file ./<FILENAME>.bicep --what-if

How to deploy the bicep files:

Note: azure-cli version 2.2.0 or higher is required.

Activate the Application Developer role in the Privileged Identity Management from Azure portal.

Set active subscription for operations az account set --subscription "<SUBSCRIPTION>"

Create a resource group for the environment az group create --name <RESOURCE GROUP> --location norwayeast --output table

Deploy the main template az deployment group create --resource-group <RESOURCE GROUP> --template-file ./<main>.bicep --output table

Deploy the app registration template az deployment group create --resource-group <RESOURCE GROUP> --template-file ./app-registration.bicep, then add the created service principal (or Enterprise App) as member to the Team Hermes Radix Admin.

Teardown (this deletes everything in the resource group) az group delete --name <RESOURCE GROUP>

Firewall and Network Configuration

Overview of network configurations and firewall rules.

Firewall is configured through Access & Network Services

Security Management

Security Checks

Security checks done every quarter.

When Who Status
Q1 xxxx username, username OK

Tasks to perform:

  • Update passwords and certificates.
  • Check users and admin accesses.

Monitoring Vulnerabilities

Identifying, review and apply security patches.

  • Snyk is used to monitor and manage security vulnerabilities in the application.
  • Dependabot is used to monitor and manage dependencies in the application.

Penetration Tests

Simulated cyberattacks carried out by Equinor's security analysts to identify and exploit vulnerabilities in the application.

Ordered from here

Date Result
xxxx

Threat Modelling Sessions

Sessions to identify, discuss, and mitigate potential security threats to a system or application.

Date Who Threat-Modeling Report
xx.xx.xxxx

See more about threat-modeling here.

Operational Tasks

Routine activities required to keep the system running smoothly.

User Management

Adding or removing users. Managing permissions and access controls.

Azure Active Directory (AD) handles user authentication and authorization.

  • Application roles are managed in the Application registration under the app roles section, here you can add roles, or remove existing ones.
  • User access are managed in the Enterprise registration under the users and groups section, here you can add new users and groups, or remove existing ones.
Monitoring System Health and Usage Statistics

Describe how system health and security monitoring is performed.

  • Application status, and logs can be monitored via the Radix Application Console, and can also from there navigate to Grafana dashboard to monitor application performance and resource utilization.
  • Usage statistics of site traffic, inspect applications logs for errors or unusual activity is available in Application Insights.
Backup and Recovery

Provide overview of backup schedules, restoration steps, and responsible personnel.

How backups is performed

How to verify backups for integrity

Recovery procedure

Security Incidents

Describe how information security incidents are handled.

Security Incidents should be reported at Equinor's Computer Security Incident Response Team as soon as identified.

Additional Resources