release_tracks: [ALPHA, BETA, GA]
help_text:
  brief: Add an IAM policy binding to an IAM service account.
  description: |
    Add an IAM policy binding to an IAM service account. A binding consists
    of at least one member, a role, and an optional condition. Adding a binding to a service account grants the specified member the specified role on the service account.

    When managing IAM roles, you can treat a service account either as a
    resource or as an identity. This command adds an IAM policy binding to a
    service account resource. There are other gcloud commands to manage IAM
    policies for other types of resources. For example, to manage IAM policies
    on a project, use the $ gcloud projects commands.

    If the service account does not exist, this command returns a `PERMISSION_DENIED` error.

  examples: |
    To add an IAM policy binding for the role of 'roles/editor' for the user 'test-user@gmail.com'
    on a service account with identifier 'my-iam-account@my-project.iam.gserviceaccount.com', run:

      $ {command} my-iam-account@my-project.iam.gserviceaccount.com --member='user:test-user@gmail.com' --role='roles/editor'

    To add an IAM policy binding for the role of 'roles/editor' to the service
    account 'test-proj1@example.domain.com', run:

      $ {command} test-proj1@example.domain.com --member='serviceAccount:test-proj1@example.domain.com' --role='roles/editor'

    To add an IAM policy binding for the role of 'roles/editor' for all authenticated users on a
    service account with identifier 'my-iam-account@my-project.iam.gserviceaccount.com', run:

      $ {command} my-iam-account@my-project.iam.gserviceaccount.com --member='allAuthenticatedUsers' --role='roles/editor'

    To add an IAM policy binding which expires at the end of the year 2018 for the role of
    'roles/iam.serviceAccountAdmin' and the user 'test-user@gmail.com' on a service account with identifier 'my-iam-account@my-project.iam.gserviceaccount.com', run:

      $ {command} my-iam-account@my-project.iam.gserviceaccount.com --member='user:test-user@gmail.com' --role='roles/iam.serviceAccountAdmin' --condition='expression=request.time < timestamp("2019-01-01T00:00:00Z"),title=expires_end_of_2018,description=Expires at midnight on 2018-12-31'

    See https://cloud.google.com/iam/docs/managing-policies for details of
    policy role and member types.
request:
  collection: iam.projects.serviceAccounts

arguments:
  resource:
    help_text: The service account to which the IAM policy binding is being added. Note that the user, group or service account in the --member flag is being granted access to this service account.
    spec: !REF googlecloudsdk.command_lib.iam.resources:service_account

iam:
  enable_condition: true
  policy_version: 3
  get_iam_policy_version_path: options_requestedPolicyVersion