Write billing and usage guide docs (#77)

Signed-off-by: Imtiaz Uddin <imtiaz@appscode.com>

Author: Imtiaz246

src/_home-billing.md

@@ -0,0 +1,10 @@
+---
+menu:
+  home_menu:
+    identifier: home-billing
+    name: Billing and Usage Guide
+    description: Billing and Usage Guide for AppsCode's products
+    link: /en/guides/billing-and-usage-guide/overview.html
+    icon: https://img.icons8.com/external-anggara-basic-outline-anggara-putra/96/external-stats-ui-anggara-basic-outline-anggara-putra.png
+    weight: 20
+---

src/en/guides/billing-and-usage-guide/_index.md

@@ -0,0 +1,13 @@
+---
+layout: 'guide'
+menu:
+  docs_menu:
+    identifier: billing-and-usage-guide
+    name: Billing and Usage Guide
+    description: Billing and Usage Guide for AppsCode's products
+    icon: https://img.icons8.com/external-anggara-basic-outline-anggara-putra/96/external-stats-ui-anggara-basic-outline-anggara-putra.png
+    popular: true
+    weight: 50
+menu_name: docs_menu
+section_menu: guides
+---

src/en/guides/billing-and-usage-guide/cost-management.md

@@ -0,0 +1,76 @@
+---
+layout: 'guide'
+menu:
+  docs_menu:
+    identifier: billing-and-usage-guide-cost-management
+    name: Cost Management
+    parent: billing-and-usage-guide
+    weight: 40
+  home_menu:
+    identifier: billing-and-usage-guide-cost-management
+    name: Cost Management
+    parent: home-billing
+    weight: 40
+menu_name: docs_menu
+section_menu: guides
+---
+
+## **Cluster and Namespace Configuration for Cost Management**
+
+For effective cost management, users can configure their clusters and namespaces. This section covers how to set a cluster's mode to **PROD** or **NON-PROD** for different billing rates, and how to enable a one-month free trial for KubeDB resources in a specific namespace.
+
+### **Configuring Cluster Mode (PROD vs. NON-PROD)**
+
+We offer different billing rates for production (**PROD**) and non-production (**NON-PROD**) environments. To distinguish between these, the user must set an annotation on the kube-system namespace of the cluster. The system considers a cluster as **PROD** only if the mode is explicitly set to `prod`. All other modes (`qa`, `staging`, `dev`) are treated as **NON-PROD**.
+
+**To set the cluster mode:**
+
+1. Identify the kube-system namespace in the cluster.
+2. Apply the following annotation: `cluster.appscode.com/mode`.
+
+Here are the possible values for the annotation:
+
+| Value | Cluster Mode Interpretation |
+| :---- | :---- |
+| prod | **PROD** (Production) |
+| qa | **NON-PROD** (Quality Assurance) |
+| staging | **NON-PROD** (Staging) |
+| dev | **NON-PROD** (Development) |
+
+**Example using kubectl:**
+
+To set a cluster to **PROD** mode, run the following command:
+
+```shell
+kubectl annotate namespace kube-system cluster.appscode.com/mode=prod --overwrite
+```
+
+To set it to a **NON-PROD** mode like staging, run:
+
+```shell
+kubectl annotate namespace kube-system cluster.appscode.com/mode=staging --overwrite
+```
+
+### **Enabling the One-Month Free Resource Trial**
+
+Users can get a one-month free trial for every KubeDB database running within a specific namespace. This allows for evaluation of the service without incurring costs during the trial period.
+
+To enable the free trial, the user needs to add a specific annotation to the desired namespace.
+
+- **Who applies this:** In a DBaaS setup, downstream users typically do not have direct access to the cluster. The annotation must be applied by the cluster/infra administrator who manages the cluster.
+- **Where it can be used:** The trial can be enabled in namespaces on both **PROD** and **NON-PROD** clusters. While the trial is active, eligible database usage is counted as **free usage** (not billed and reported as Free usage in the Billable section), regardless of cluster mode. After the trial ends for a database, subsequent usage follows the cluster's pricing mode (**PROD** or **NON-PROD**) and your contract status (paid contract vs. the 30‑day free contract when no paid contract exists).
+
+**To enable the trial:**
+
+1. Select the namespace that contains your KubeDB databases. Any existing databases in this namespace that have not previously received a trial will receive a one-month free trial starting from when the annotation is applied. Any databases created later in this namespace will also automatically receive a one-month free trial. Databases that have already used a trial are not eligible again.
+2. Apply the annotation `ace.appscode.com/enable-resource-trial` with the value `true`.
+
+**Example using kubectl:**
+
+To enable the free trial for a namespace named `my-app-ns`, run the following command:
+
+```shell
+kubectl annotate namespace my-app-ns ace.appscode.com/enable-resource-trial=true --overwrite
+```
+
+Once this annotation is applied, all KubeDB resources deployed within the my-app-ns namespace will automatically receive a one-month free trial.

src/en/guides/billing-and-usage-guide/dbaas-client-billing.md

@@ -0,0 +1,118 @@
+---
+layout: 'guide'
+menu:
+  docs_menu:
+    identifier: billing-and-usage-guide-dbaas-client-billing
+    name: DBaaS Client Billing
+    parent: billing-and-usage-guide
+    weight: 30
+  home_menu:
+    identifier: billing-and-usage-guide-dbaas-client-billing
+    name: DBaaS Client Billing
+    parent: home-billing
+    weight: 30
+menu_name: docs_menu
+section_menu: guides
+---
+
+### **DBaaS Provider Billing APIs**
+
+This section is intended for DBaaS providers (self-hosted administrators) who manage the platform for end-users. To help providers monitor the resource consumption of their clients, we expose a set of APIs that deliver detailed usage reports for specific namespaces. This is particularly useful for billing, resource planning, and gaining insights into how end-users are utilizing the KubeDB resources within their assigned namespaces.
+
+#### **Prerequisites: Enabling Client Billing**
+
+Before these APIs can be used, the **Client Billing** feature must be enabled in your contract with us. This is a digital agreement that activates the necessary backend services to collect and expose usage data for your clients' namespaces from our central system.
+
+For more information on how to view or modify your contract, please refer to the [official contract management documentation](https://appscode.com/docs/en/guides/license-management/contract.html) or contact [AppsCode administrators](https://appscode.com/contact/). Once **Client Billing** is enabled in your contract, you can proceed to use the API endpoints detailed below.
+
+### **Authentication**
+
+To use these APIs, you must authenticate your requests. Usage information is collected and stored in our central system, and accessing it requires a secure token.
+
+1. **Generate an Access Token:** Create a user-scoped API token from your account.
+   - Go to User Settings and open the `Tokens` tab, then click on `Generate Token`.
+     ![Navigate to API Tokens](./images/create-token-ui-navigation.png)
+   - Provide a token name and (optionally) an expiry, then click on `Generate`.
+     ![Create token options](./images/create-token-options.png)
+   - Copy the token and store it securely. It’s shown only once.
+     ![Copy the generated token](./images/created-token-result.png)
+2. **Use as a Bearer Token:** This token must be included in the Authorization header of your API requests as a Bearer token.
+
+**Example Header:** Authorization: Bearer <YOUR_ACCESS_TOKEN>  
+
+**Note:** Treat this access token as a confidential credential. Do not expose it in client-side code or public repositories.
+
+### **Information Available for Client-Side Billing**
+
+The billing reports expose the following information for use in customer invoicing and internal chargeback. This section describes what you can expect to see; the next section explains how to query it via APIs.
+
+1) Namespace Level
+   - **Database Information:** Identifies the type of database deployed in each namespace (for example, MongoDB, PostgreSQL, MySQL), along with the database name as visible to the platform.
+
+2) Database Level
+   - **Pod Details:**
+     - **Flavor:** CPU and Memory allocation for each pod.
+     - **Age of Pod:** Duration since pod creation.
+     - **Number of Pods:** Total pod count, including autoscaling pods.
+   - Volume Details:
+     - **Volume Name:** Name of the persistent volume.
+     - **Initial Size:** Initial size of the volume at creation.
+     - **Expanded Sizes:** Any volume size increases, including the size and timestamp of each expansion.
+     - **Volume Created At:** Timestamp when the volume was created.
+     - **Volume Age:** Duration since the volume was created.
+     - **Volume Expansion History:** Record of any expansion events, with size and timestamp.
+     - **Volume Deleted At:** Timestamp when the volume was deleted (if applicable).
+
+**Notes:** Timestamps are reported in UNIX time. Sizes are returned as strings with Gi units (for example, '10Gi').
+
+### **API Endpoints**
+
+The following APIs are available to retrieve billing and usage reports.
+
+#### **1. Get Usage Reports for All Namespaces**
+
+This endpoint retrieves a consolidated usage report for all namespaces that are bound to your client organizations. It is ideal for generating auditing reports and getting a high-level overview of resource consumption.
+
+* **Endpoint:** 
+> GET https://appscode.com/api/v1/dbaas/billing/reports/namespaces
+* **Description:** Returns a list of usage reports, with each report corresponding to a namespace managed under your DBaaS platform. This endpoint is particularly useful for auditing, billing reconciliation, and high‑level usage analysis.
+* **Query Parameters:**
+    * **org** (string, optional): The organization name in the central **appscode.com** platform that owns your billing contract and receives usage from your self-hosted installation. The authenticated user must be a member of this organization. Use this to restrict results to namespaces reported under that org.
+* **Limitations:**
+    * The current implementation does not support pagination. As a result, the endpoint returns all available namespaces, which may lead to large response sizes over time.
+    * Resources (including namespaces, pods, and volumes) that were deleted more than six months ago are automatically excluded from the response.
+* **Example Response:** The response will contain a list of namespace reports. Each report includes cluster information, namespace details, and a breakdown of the databases running within that namespace. Please see the [Additional Resources](#additional-resources) section below for detailed response schema and example.
+
+#### **2. Get Usage Report for a Specific Namespace**
+
+This endpoint allows you to drill down and retrieve a detailed usage report for a single, specific namespace within a given cluster. This is useful for generating invoices or analyzing the consumption of a particular client.
+
+* **Endpoint:** 
+> GET https://appscode.com/api/v1/dbaas/billing/reports/clusters/{clusterID}/namespaces/{namespace}
+* **Description:** Returns a detailed usage report for the specified namespace, including information about the cluster, the namespace itself, and all KubeDB resources deployed within it.
+* **Path Parameters:**
+    * **clusterID** (string, required): The unique identifier of the spoke cluster where the namespace is located.
+    * **namespace** (string, required): The name of the namespace for which the report is being requested.
+* **Query Parameters:**
+    * **org** (string, optional): The organization name in the central **appscode.com** platform that owns your billing contract and to which your self-hosted app reports usage. The authenticated user must be a member of this organization. Provide the org created for your DBaaS customer to target the correct data.
+* **Cautions:**
+    * The namespace name provided in the path should be unique within the specified cluster, or unique across all clusters if you need to ensure you are targeting the correct one.
+    * In the self-hosted platform, each **client organization** (client-org) name must be unique because the DBaaS namespace is created with exactly the same name as that client-org. This one-to-one mapping means duplicate client-org names will cause namespace conflicts.
+    * You can optionally add an annotation to the namespace to tag the downstream end-user (for example, a customer ID or external reference) so you can map reports back to your own user records.
+* **Response Breakdown:** The JSON response for a single namespace provides granular details:
+    * **clusterInfo**: Contains metadata about the cluster, such as its name, Kubernetes version, provider, and resource capacity.
+    * **namespaceInfo**: Includes the namespace's labels, annotations, and creation timestamp.
+    * **databases**: An array of objects, where each object represents a KubeDB instance and contains:
+        * **databaseInfo**: Basic details like the database kind, product, and resource name.
+        * **podDetails**: Information about the pods, including CPU and memory resources allocated.
+        * **volumeDetails**: Details about the persistent volumes, including their initial size and any expansion history.
+
+For full field-by-field schemas, sample payloads, and screenshots, see the [Additional Resources](#additional-resources) section below.
+
+### **General API Cautions**
+
+- **Time Format:** All time-related values in the API responses (e.g., createdAt, lastReceivedAt) are represented in the **UNIX time format**.
+- **Data Retention:** The API response does not include resources (namespaces, pods, volumes, etc.) that were deleted more than **six months ago**.
+
+### **Additional Resources**
+- **Document Files:** For related document files, please access the following shared drive: [DBaaS Billing API Documents](https://drive.google.com/drive/u/1/folders/14ccceVuJQCKLvi9iSswnz86LqvB3Dfeq)