gcpapi

README

Strategies for understanding the Google Cloud API

It can be difficult to understand the Google Cloud Platform API documentation, and the Go client libraries are not always easy to use as a result. Consider an example where we want to update the policy of a service account. The API documentation is here, and the Go client library is here. However, there is little documentation of response codes, etc.

Note: not all the SDKs and API documentation are as challenging as this example, but the strategies can still be useful

Using gcloud CLI

It can be useful to try running the equivalent glcoud by adding the --log-http flag to the command, e.g.:

$ gcloud iam service-accounts add-iam-policy-binding service --member meh --role meh --log-http

=======================
==== request start ====
uri: https://iam.googleapis.com/v1/projects/nada-dev-db2e/serviceAccounts/service:getIamPolicy?alt=json&options.requestedPolicyVersion=3
method: POST
== headers start ==
b'accept': b'application/json'
b'accept-encoding': b'gzip, deflate'
b'authorization': --- Token Redacted ---
b'content-length': b'0'
b'x-goog-api-client': b'cred-type/u'
== headers end ==
== body start ==

== body end ==
==== request end ====
---- response start ----
status: 404
-- headers start --
Alt-Svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
Cache-Control: private
Content-Encoding: gzip
Content-Type: application/json; charset=UTF-8
Date: Thu, 22 Feb 2024 08:31:10 GMT
Server: ESF
Transfer-Encoding: chunked
Vary: Origin, X-Origin, Referer
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 0
-- headers end --
-- body start --
{
  "error": {
    "code": 404,
    "message": "Unknown service account",
    "status": "NOT_FOUND"
  }
}

-- body end --
total round trip time (request+response): 0.877 secs
---- response end ----
----------------------
ERROR: (gcloud.iam.service-accounts.add-iam-policy-binding) NOT_FOUND: Unknown service account

Reading the terraform provider code

If you don't want to work out the details on your own, it can be useful to read the code of the terraform provider for Google Cloud as it is also written in go. For example, here is the PR that adds the google_project_iam_binding and google_project_iam_member resources.

• https://github.com/hashicorp/terraform-provider-google/tree/main

Documentation

Index

• func IsGoogleApiErrorWithCode(err error, errCode int) bool
• func NewBinding(role, member string) *iam.Binding
• func ServiceAccountEmail(name, project string) string
• func ServiceAccountEmailMember(name, project string) string
• func ServiceAccountKubernetesMember(name, namespace, project string) string
• func ServiceAccountResource(name, project string) string
• func ServiceAccountTokenCreatorRoleBinding(name, project string) *iam.Binding
• type ServiceAccountChecker
  • func NewServiceAccountChecker(project string, fetcher ServiceAccountFetcher) ServiceAccountChecker
• type ServiceAccountFetcher
  • func NewServiceAccountFetcher(project string, service *iam.Service) ServiceAccountFetcher
• type ServiceAccountPolicyBinder
  • func NewServiceAccountPolicyBinder(project string, manager ServiceAccountPolicyManager) ServiceAccountPolicyBinder
• type ServiceAccountPolicyManager
  • func NewServiceAccountPolicyManager(project string, service *iam.Service) ServiceAccountPolicyManager
• type ServiceAccountRole
  • func (r ServiceAccountRole) String() string

Functions

func IsGoogleApiErrorWithCode

func IsGoogleApiErrorWithCode(err error, errCode int) bool

Borrowed from Hashicorp's GCP provider: - https://github.com/hashicorp/terraform-provider-google/blob/main/google/transport/transport.go#L150-L153

func NewBinding

func NewBinding(role, member string) *iam.Binding

func ServiceAccountEmail

func ServiceAccountEmail(name, project string) string

func ServiceAccountEmailMember

func ServiceAccountEmailMember(name, project string) string

func ServiceAccountKubernetesMember

func ServiceAccountKubernetesMember(name, namespace, project string) string

func ServiceAccountResource

func ServiceAccountResource(name, project string) string

ServiceAccountResource returns a fully qualified resource name for a service account. - https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts/getIamPolicy

func ServiceAccountTokenCreatorRoleBinding

func ServiceAccountTokenCreatorRoleBinding(name, project string) *iam.Binding

Types

type ServiceAccountChecker

type ServiceAccountChecker interface {
	Exists(ctx context.Context, name string) (bool, error)
}

func NewServiceAccountChecker

func NewServiceAccountChecker(project string, fetcher ServiceAccountFetcher) ServiceAccountChecker

type ServiceAccountFetcher

type ServiceAccountFetcher interface {
	Get(ctx context.Context, name string) (*iam.ServiceAccount, error)
}

func NewServiceAccountFetcher

func NewServiceAccountFetcher(project string, service *iam.Service) ServiceAccountFetcher

type ServiceAccountPolicyBinder

type ServiceAccountPolicyBinder interface {
	AddPolicyRole(ctx context.Context, name string, role ServiceAccountRole) (*iam.Policy, error)
	RemovePolicyRole(ctx context.Context, name string, role ServiceAccountRole) (*iam.Policy, error)
}

func NewServiceAccountPolicyBinder

func NewServiceAccountPolicyBinder(project string, manager ServiceAccountPolicyManager) ServiceAccountPolicyBinder

type ServiceAccountPolicyManager

type ServiceAccountPolicyManager interface {
	GetPolicy(ctx context.Context, resource string) (*iam.Policy, error)
	SetPolicy(ctx context.Context, resource string, policy *iam.Policy) (*iam.Policy, error)
}

func NewServiceAccountPolicyManager

func NewServiceAccountPolicyManager(project string, service *iam.Service) ServiceAccountPolicyManager

type ServiceAccountRole

type ServiceAccountRole string

const (
	ServiceAccountTokenCreatorRole ServiceAccountRole = "roles/iam.serviceAccountTokenCreator"
	WorkloadIdentityUser           ServiceAccountRole = "roles/iam.workloadIdentityUser"
)

func (ServiceAccountRole) String

func (r ServiceAccountRole) String() string