Google Drive (native `gdrive`)

kopia has a native Google Drive backend, called gdrive. It talks to Drive directly with a Google service-account key, with no rclone in between. Kopiur exposes it as backend.gdrive.

When to use native gdrive vs rclone

Both reach Google Drive. They differ in how they connect:

Native gdrive. kopia talks to the Drive API directly with a service-account JSON. There are fewer moving parts at connect time, and no embedded rclone serve or WebDAV bridge.
rclone Drive remote. kopia shells out to rclone, which can be slower to come up during repository connect. Use it if you already run rclone, or if you need OAuth-user authentication rather than a service account.

Provider prerequisites

A Google Cloud service account with a JSON key, and the Drive API enabled on its project.
A Drive folder to hold the repository. Copy its folder ID, which is the last path segment of the folder URL https://drive.google.com/drive/folders/<FOLDER_ID>.
Share the folder with the service account’s client_email as an Editor. Without that, the mover gets a permission error on connect.

The Secret shape

gdrive is file-delivered. The mover reads the whole service-account JSON from a well-known environment key, writes it to a private file with mode 0600, and runs kopia with --credentials-file.

Secret key	Required	What it is
`KOPIA_GDRIVE_CREDENTIALS`	yes¹	The entire service-account key JSON, exactly as issued. Written to a file, then passed as `--credentials-file`.
`KOPIA_PASSWORD`	yes	The repository encryption password.

¹ Optional in the schema. When it is absent, kopia falls back to ambient credentials, meaning GOOGLE_APPLICATION_CREDENTIALS or instance metadata. In a normal cluster you supply the Secret.

The Repository

---
apiVersion: v1
kind: Secret
metadata:
  name: gdrive-repo-creds
  namespace: backups
type: Opaque
stringData:
  # The full service-account key JSON, verbatim. The mover writes it to a file
  # and passes `--credentials-file` to kopia. The key MUST be
  # KOPIA_GDRIVE_CREDENTIALS (a valid env identifier) — a dotted key like
  # `credentials.json` is dropped by Kubernetes envFrom.
  KOPIA_GDRIVE_CREDENTIALS: |
    {
      "type": "service_account",
      "project_id": "REPLACE_ME",
      "private_key_id": "REPLACE_ME",
      "private_key": "-----BEGIN PRIVATE KEY-----\nREPLACE_ME\n-----END PRIVATE KEY-----\n",
      "client_email": "kopia@REPLACE_ME.iam.gserviceaccount.com",
      "client_id": "REPLACE_ME",
      "token_uri": "https://oauth2.googleapis.com/token"
    }
  KOPIA_PASSWORD: "choose-something-long-and-random"
---
apiVersion: kopiur.home-operations.com/v1alpha1
kind: Repository
metadata:
  name: gdrive-primary
  namespace: backups
spec:
  backend:
    gdrive:
      # The Drive folder ID that holds the repository. Share this folder with the
      # service account's client_email (above) as an Editor.
      folderId: REPLACE_ME_FOLDER_ID
      credentialsSecretRef:
        name: gdrive-repo-creds # Secret carrying KOPIA_GDRIVE_CREDENTIALS above
  encryption:
    passwordSecretRef:
      name: gdrive-repo-creds # may be the same Secret; it also carries KOPIA_PASSWORD
      key: KOPIA_PASSWORD
  # `create` now defaults to enabled (connect-or-create is idempotent); set
  # `create.enabled: false` only for a strictly read-only / externally-managed repo.

Fields reference (`backend.gdrive`)

Field	Required	Default	Example	What it controls
`folderId`	yes	—	`0AbCdEf...`	The Drive folder ID that holds the repository. It is the last segment of the folder URL.
`credentialsSecretRef`	no¹	—	`{ name: gdrive-repo-creds }`	Secret holding the service-account JSON under `KOPIA_GDRIVE_CREDENTIALS`. A `ClusterRepository` adds `namespace:`.

¹ Optional in the schema. In practice it is required, unless the mover already has ambient Google credentials.

Customization — the values you actually change

folderId selects which Drive folder backs the repository. Share that folder with the service account.
KOPIA_GDRIVE_CREDENTIALS holds the service-account JSON. Rotate it by re-pasting.
create.enabled defaults to true, because connect-or-create is idempotent. Set it to false only for a read-only or externally-managed repository.

As a `ClusterRepository`

The same backend.gdrive stanza works on a cluster-scoped ClusterRepository, with two requirements. The credentialsSecretRef, and the encryption.passwordSecretRef, must carry an explicit namespace:. And the Secret must exist in the namespaces the movers run in. See Movers.

Troubleshooting

403 or permission denied on connect. Either the Drive folder isn’t shared with the service account’s client_email, which needs Editor, or the Drive API isn’t enabled on the service account’s project.
folderId not found. Copy the ID from the folder URL, not the folder name.
Slow or contradictory results compared to an old rclone Drive repository. They are different repositories. A native gdrive repository can’t read rclone-written data.