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:

Global Organization Billing Account Admin: create, manage, and bind the BillingAccount resource. Ask your Organization IAM admin to grant you the organization-billing-account-admin role.
Global 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.
Global 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 Global API server, ensure you have the following resources:

Sign in and generate the kubeconfig file for the Global API server if you don't have one.
Use the path to the kubeconfig file of the Global API server to replace GLOBAL_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.global.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.global.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 Global API server:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f billingaccount.yaml
```
Replace GLOBAL_API_SERVER_KUBECONFIG with the Global 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.global.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 GLOBAL_API_SERVER_KUBECONFIG apply -f billingaccountbinding.yaml

Check the status of the BillingAccountBinding and verify that there are no errors:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe billingaccountbinding billing -n PROJECT_NAME
```
Replace PROJECT_NAME with the name of the project bound to the billing account.

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.global.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 GLOBAL_API_SERVER_KUBECONFIG apply -f billingaccountbinding.yaml

Check the status of the BillingAccountBinding and verify that there are no errors:

kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe billingaccountbinding billing -n platform

List billing account bindings

View a list of all deployed BillingAccountBinding resources and their current status across all namespaces in the organization:

  kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG get billingaccountbinding -A -o 'custom-columns=NAME:metadata.name,NAMESPACE:metadata.namespace,BillingAccountName:spec.billingAccountRef.name,STATUS:status.conditions[0].status'

This command outputs the NAME, NAMESPACE, BillingAccountName, and STATUS of each BillingAccountBinding. The STATUS field indicates whether the binding is active or if there are any errors.

Billing account hierarchy and behavior

When linking billing accounts to organizations and projects, the following hierarchy and behaviors apply:

Project-level association takes precedence: If a specific project, such as project-A, is explicitly linked to a BillingAccount (such as billing-account-1), then all costs for project-A are billed exclusively to billing-account-1. This project-level association remains valid regardless of any organization-level billing account settings.
Organization-level association for unlinked projects: If your organization is linked to a BillingAccount (such as billing-account-0), all projects within that organization that do not have their own explicit BillingAccountBinding are automatically associated with and billed to billing-account-0. This association typically takes effect after approximately 15 minutes.
Changing organization billing accounts: If the billing account linked to an organization changes (such as from billing-account-0 to billing-account-new), projects that were previously inheriting billing-account-0 do not automatically switch to billing-account-new. These projects remain bound to billing-account-0, and their billing account must be manually updated if you want them to use billing-account-new.

Change the linked billing account

In Distributed Cloud, you can't delete a billing account. If you require a change to your billing configuration, you must change the billing account that is linked to an organization or project 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.

Change the linked billing account for a project

Follow these steps to change the linked billing account for a project:

Create a new BillingAccount to link to the project. This account replaces the old account.
Locate the BillingAccountBinding resource YAML file in the project namespace to see which billing account is linked:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe billingaccountbinding billing -n PROJECT_NAME
```
Modify the BillingAccountBinding to link to the new billing account. In the billingAccountRef section, populate the name field with a new BillingAccount name created in step 1 of this section.
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG edit billingaccountbinding billing -n PROJECT_NAME
```

After making the changes, ensure that the billing account is correctly updated:

kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe billingaccountbinding billing -n PROJECT_NAME

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

  apiVersion: billing.global.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.global.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

Change the linked billing account for an organization

Follow these steps to change the linked billing account for an organization:

Create a new BillingAccount to link to the organization. This account replaces the old account.
Locate the BillingAccountBinding resource YAML file in the platform namespace to see which billing account is linked:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG describe billingaccountbinding billing -n platform
```
Modify the BillingAccountBinding to link to the new billing account. In the billingAccountRef section, populate the name field with a new BillingAccount name created in step 1.
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG edit billingaccountbinding billing -n platform
```