Create and link billing accounts

Google Distributed Cloud (GDC) air-gapped environments require a billing account to track costs for projects and organizations. If you don't link a billing account to an organization or project, you'll lose cost data associated with the resource.

To charge service usage to the customer, all billing accounts within an organization use a single price sheet.

Before you begin

Ask your Organization IAM Admin to grant you the following required roles. These roles bind to either the project namespace for project-level billing, or the platform namespace for organization-level billing:

Organization Billing Account Administrator: create, manage, and bind the BillingAccount resource. Ask your Organization IAM admin to grant you the organization-billing-account-admin role.
Organization Billing Account User: read, list, and bind the BillingAccount resource. Ask your Organization IAM admin to grant you the organization-billing-account-user role.
Organization Billing Account Manager: read, list, create, and update the BillingAccountBinding resource. Ask your Organization IAM admin to grant you the organization-billing-manager role.

Get the kubeconfig file

To run commands against the Management API server, ensure you have the following resources:

Sign in and generate the kubeconfig file for the Management API server if you don't have one.
Use the path to the kubeconfig file of the Management API server to replace MANAGEMENT_API_SERVER_KUBECONFIG in these instructions.

Create a new billing account

A billing account is uniquely identified by its name and namespace. To create a billing account, use a custom resource to establish the name and namespace:

Create a YAML file, and add the BillingAccount custom resource and the following contents:
```
apiVersion: billing.gdc.goog/v1
kind: BillingAccount
metadata:
  namespace: platform
  name: BIL_ACCOUNT_NAME
spec:
  displayName: BIL_DISPLAY_NAME
  paymentSystemConfig:
    cloudBillingConfig:
      accountID: "012345-6789AB-CDEF01"
```
Replace the following variables:
- BIL_ACCOUNT_NAME: the name of the billing account. For example, test-billing-account.
- BIL_DISPLAY_NAME: the billing account display name. For example, "Test Billing Account".
Verify your payment configuration type. Distributed Cloud billing accounts must have one of the following payment configurations:
- cloudBillingConfig: the default payment configuration. This configuration stores a Cloud Billing account ID.
- customConfig: a custom configuration for partners to store their payment configuration to bill the organization. customConfig supports a dictionary of key-value strings, with a mandatory key payment-config-type.
The following examples show BillingAccount YAML file snippets for different payment configurations:

cloudBillingConfig
```
spec:
  paymentSystemConfig:
    cloudBillingConfig:
      accountID: CLOUD_BILLING_ACCOUNT_ID
```
Replace CLOUD_BILLING_ACCOUNT_ID with your Google Cloud billing account ID.

customConfig
```
spec:
 paymentSystemConfig:
   customConfig:
      "payment-config-type": PAYMENT_CONFIG_TYPE
```
Replace PAYMENT_CONFIG_TYPE with your chosen payment configuration type for your custom billing configuration.

If you don't have the information for your organization's customConfig configuration, enter the following details:
```
spec:
 paymentSystemConfig:
   customConfig:
      "payment-config-type": "N/A"
```
The following YAML file shows a complete BillingAccount resource with the cloudBillingConfig configuration:
```
apiVersion: billing.gdc.goog/v1
kind: BillingAccount
metadata:
  namespace: platform
  name: test-billing-account
spec:
  displayName: "Test Billing Account"
  paymentSystemConfig:
    cloudBillingConfig:
      accountID: "012345-6789AB-CDEF01"
```
Save the YAML file. Run the kubectl CLI to apply the resource in the Management API server for the specific organization or project you want to bill:
```
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f billingaccount.yaml
```
Replace MANAGEMENT_API_SERVER_KUBECONFIG with the Management API server kubeconfig file.

Link an organization or project to a billing account

This section provides a series of steps to link an organization or project to a BillingAccount.

Link a project

To link a project to a BillingAccount, do the following:

Add the following contents to the file: billingaccountbinding.yaml:
- In the billingAccountRef section, populate the name field with the content from the name field in the BillingAccount you want to link.
- In the metadata section, populate the namespace field with the content from the identical field in the BillingAccount resource.
In this example, the project namespace is PROJECT_NAME:
```
apiVersion: billing.gdc.goog/v1
kind: BillingAccountBinding
metadata:
  name: billing
  namespace: PROJECT_NAME
spec:
  billingAccountRef:
    name: BIL_ACCOUNT_NAME
    namespace: platform
```
Replace PROJECT_NAME with the name of the project bound to the billing account.

Run the following kubectl command to apply the billingaccountbinding.yaml file:

kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f billingaccountbinding.yaml

Link an organization

To link an organization to a BillingAccount, do the following:

Add the following content to the YAML file billingaccountbinding.yaml:
- In the billingAccountRef section, populate the name field with the content from the name field in the BillingAccount you want to link.
- In the metadata section, populate the namespace field with the content from the identical field in the BillingAccount resource. In this example, the organization namespace is platform:
```
apiVersion: billing.gdc.goog/v1
kind: BillingAccountBinding
metadata:
  name: billing
  namespace: platform
spec:
  billingAccountRef:
    name: BIL_ACCOUNT_NAME
    namespace: platform
```

Run the following kubectl command to apply the billingaccountbinding.yaml file:

kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f billingaccountbinding.yaml

Unlink billing accounts from an organization or project

In Distributed Cloud, you can't delete a billing account. If you require a change to your billing configuration, you must unlink an organization or project from an existing billing account by modifying the BillingAccountBinding. Some scenarios for this use case include the following examples:

Accounting rules within your company ask that you split charges associated with developer and production-level workloads into separate accounts.
You create a billing account to charge a customer contract for a one year period. When the contract expires, you must charge for the remaining period that exceeds a year.

To unlink a billing account from an organization or project, do the following:

Create a new BillingAccount to link to the project. This account will replace the old account.
Locate the BillingAccountBinding resource YAML file in the project or platform namespace, and modify the following fields:
- In the billingAccountRef section, populate the name field with a new BillingAccount name.

The following example shows a BillingAccountBinding YAML file with the account expired-billing-account linked to the project project-one:

  apiVersion: billing.gdc.goog/v1
  kind: BillingAccountBinding
  metadata:
    # The name of a BillingAccountBinding will typically always be `billing`.
    name: billing
    # This is the project.
    namespace: project-one
  spec:
    billingAccountRef:
      # This is an example of a BillingAccount that has expired.
      name: expired-billing-account
      namespace: platform

The following example shows the BillingAccountBinding YAML file from the earlier example modified to link a new account called new billing account:

  apiVersion: billing.gdc.goog/v1
  kind: BillingAccountBinding
  metadata:
    name: billing
    # This is the project.
    namespace: project-one
  spec:
    billingAccountRef:
      # This is the example of the new BillingAccount.
      name: new-billing-account
      namespace: platform