# Get Started with Infra API

This document will guide you on how to use Infra API.

## Access Infra API

Infra API can be accessed via kubectl with your Google identity.

1. Follow [DBaaS Operation 101](https://github.com/tidbcloud/infra/blob/master/docs/operation-101.md) to ensure:
    * `gcloud` cli is installed
    * `dev-base-us-west-2` kubernetes context is configured (similarly, ensure `staging-base-us-west-2` context is configured if you want to access Infra API staging)

2. Verify the prerequisites

    ```bash
    $ gcloud auth list
    $ kubectl config current-context
    ```

3. Edit the [dev](https://github.com/tidbcloud/infra-cd/blob/3a2dab214e285ada2db281ecf60bddbc488f253f/projects/infra-api/Pulumi.dev.yaml#L4) or [staging](https://github.com/tidbcloud/infra-cd/blob/3a2dab214e285ada2db281ecf60bddbc488f253f/projects/infra-api/Pulumi.staging.yaml#L4) permission configs, and submit a PR to Apply for the read-only permission.

4. After the PR get merged, retrieve the `kubeconfig` file that configures kubectl to use your Google identity

    ```bash
    $ kubectl get secret api-server-oidc-kubeconfig -n infra --template={{'.data.config'}} | base64 -d > ~/.kube/dev-infra.kubeconfig
    $ export KUBECONFIG=~/.kube/dev-infra.kubeconfig
    ```

5. Test the access

    ```bash
    $ kubectl get providers.cloud.pingcap.com
    ```

## Use Infra API

Infra API resources are isolated by [Namespace](../reference/namespace.md), the following example using `-A` to retrieve
resources across all namespaces. You may replace `-A` with `-n <your-namespace>` for clarity.

> **NOTE**: the resources written by [DBaaS Central](https://github.com/tidbcloud/dbaas) are located in `${centralENV}-${projectId}` namespaces, e.g. `nightly-1`, `staging-1`, `louis-1`, etc.

```bash
# list Networks, Network is a container for Cluster
$ kubectl get networks -A

# inspect the spec and status of a network
$ kubectl describe networks -n nightly-1 aws-us-west-2
# alternatively, use -oyaml if you need structure output
$ kubectl get networks -n nightly-1 aws-us-west-2 -oyaml

# list Clusters
$ kubectl get clusters -A
# inspect a cluster
$ kubectl describe clusters -n nightly-1 <name>

# list all backups
$ kubectl get backups -A
# list running backups
$ kubectl get backups -A | grep Running
# inspect a backup
$ kubectl describe backups -n nightly-1 mybackup-270008

# list network peerings
$ kubectl get networkpeers -A
# inspect a peering
$ kubectl describe networkpeers -n nightly-1269307563199959040 aws-us-west-2-networkpeer
```

For more details about each API object, please refer to [Infra API Reference](../reference/README.md)

## Programmatical Access

Reference: [Access Infra API using Generic Kubernetes Client](../reference/README.md#generic-client)

## Advanced Topics

### Migrate Central to Infra API

You may enable Infra API for your central instance by setting the following configurations in your pulumi config file:

```yaml
  dbaas:enableNetwork: "true"
  dbaas:enableBackupRestoreRead: "true"
  dbaas:enableBackupRestoreWrite: "true"
  dbaas:enableClusterRead: "true"
  dbaas:enableClusterWrite: "true"
  dbaas:enableNetworkPeerRead: "true"
  dbaas:enableNetworkPeerWrite: "true"
  dbaas:projectIDAsInfraProjectID: "false"
```

The resources created before Infra API in shared environments including `nightly`, `staging` and `prod` have already been migrated to Infra API. But the migration did not work for personal central instance, there are two options to make the integration work:

* destroy the current central deployment and create a new one with Infra API enabled
* create a new project in your current central deployment and discard the existing projects

### Grant Write Permissions

[Access Infra API](#access-infra-api) only grants read permission for security. If you do have the reason to write Infra API manually, you may submit a PR to create a [RBAC with write permission for your Google identity](https://github.com/tidbcloud/infra-cd/blob/3a2dab214e285ada2db281ecf60bddbc488f253f/infra-api.ts#L172) in Infra API, the permissions will be granted after the PR get merged.

### Diagnose Infra API Problems

Steps to diagnose when you think Infra API does not work as your expectation:

1. Inspect the status of the object, e.g. `kubectl get clusters -n <ns> <name> -oyaml`
2. Search the logs of Infra API, with your object name as the keyword, e.g. [search logs about cluster 1373933076657971855 in staging](https://grafana.oauth.staging.shared.aws.tidbcloud.com/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22loki%22,%7B%22expr%22:%22%7Binstance%3D~%5C%22infra-provider.*%5C%22%7D%20%7C%3D%20%5C%221373933076657971855%5C%22%22%7D%5D)
3. Post a topic in "Cloud Dev" on lark and ask Infra API developers for help