# About the asmcli

The `asmcli` is a Google-provided tool that you can use to install or
upgrade Cloud Service Mesh. If you let it, `asmcli` will configure your
project and cluster as follows:

- Grant you the required Identity and Access Management (IAM) permissions on your Google Cloud project.
- Enable the required Google APIs on your Google Cloud project.
- Set a label on the cluster that identifies the mesh.
- Create a service account that lets data plane components, such as the sidecar proxy, securely access your project's data and resources.
- [Register the cluster](https://docs.cloud.google.com/anthos/multicluster-management/connect/registering-a-cluster) to the fleet if it isn't already registered.

Just include the `--enable_all` flag when you run `asmcli` to let it configure
your project and cluster. For more information about `asmcli` options and flags,
see the [`asmcli` reference](https://docs.cloud.google.com/service-mesh/v1.20/docs/unified-install/reference.md.txt).

Next, `asmcli` configures YAML files with your project and cluster information.
These configuration files are needed to install the Cloud Service Mesh control plane.

If you are new to Cloud Service Mesh and Istio, skip ahead to
[Supported platforms](https://docs.cloud.google.com/service-mesh/v1.20/docs/unified-install/asmcli-overview.md.txt#supported_platforms). The next section is intended to
help existing Cloud Service Mesh upgrade to 1.31.

## Transitioning to `asmcli`

The `asmcli` takes the place of `istioctl install` and `install_asm`. Although
you can still use the legacy tools in Cloud Service Mesh 1.11, we are deprecating
them and they will no longer be supported in Cloud Service Mesh 1.12 and later.
Please update your scripts and tools to use `asmcli`.

With Cloud Service Mesh 1.11 and later, all clusters must be registered to a
[fleet](https://docs.cloud.google.com/anthos/multicluster-management/fleets). See
[Fleet requirements](https://docs.cloud.google.com/service-mesh/v1.20/docs/unified-install/anthos-service-mesh-prerequisites.md.txt#fleet_requirements)
for details.

### Transitioning from `install_asm`

If you are familiar with `install_asm`, `asmcli` is similar but with the
following notable differences:

- You use `asmcli install` for new installations and upgrades.
  There isn't a
  [`--mode` option](https://docs.cloud.google.com/service-mesh/v1.20/docs/unified-install/reference.md.txt#options) like with
  `install_asm`. When you run `asmcli install`, it checks to see if
  there's an existing control plane on the cluster. If there isn't an existing
  control plane, `asmcli` installs Cloud Service Mesh. If the cluster has an
  existing control plane (either a Cloud Service Mesh control plane or an open source
  Istio control plane):

  - If the revision label on the existing control plane doesn't match the
    revision label for the new control plane, `asmcli` does a
    [canary upgrade](https://docs.cloud.google.com/service-mesh/v1.20/docs/unified-install/plan-upgrade.md.txt#about_canary_upgrades).

  - If the control plane revision labels are the same, `asmcli` does an in-place
    upgrade.

- Most of the `asmcli`
  [options and flags](https://docs.cloud.google.com/service-mesh/v1.20/docs/unified-install/reference.md.txt) behave the same
  as the ones for `install_asm`.

### Transitioning from `istioctl install`

If you are familiar with `istioctl install`, if you normally pass an
`IstioOperator` YAML file using the `-f` command-line argument to configure the
control plane, you can pass the file to `asmcli` using the `--custom_overlay`
option. In the Cloud Service Mesh documentation, we refer to these files as overlay
files.

> [!NOTE]
> **Note:** By default, `asmcli` doesn't install an ingress gateway with the control plane. For production deployments, we recommend that you install gateways separately. For more information and best practices, see [Install and upgrade gateways](https://docs.cloud.google.com/service-mesh/v1.20/docs/gateways.md.txt#best_practices_for_deploying_gateways). We have provided sample Deployment, Service, ServiceAccount, and Role configuration files in the [`anthos-service-mesh`](https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages/tree/main/samples/gateways) repository for both ingress and egress gateways to get you started. You can deploy them as they are or customize them as needed.

## Supported platforms

Cloud Service Mesh installations on the list of
[Supported platforms](https://docs.cloud.google.com/service-mesh/v1.20/docs/supported-platforms.md.txt) can be configured
or upgraded by `asmcli`.

However, not all features are available on the platforms outside of Google Cloud.
For details, see
[In-cluster control plane supported features](https://docs.cloud.google.com/service-mesh/v1.20/docs/supported-features.md.txt).

## What's next

- [Prerequisites](https://docs.cloud.google.com/service-mesh/v1.20/docs/unified-install/anthos-service-mesh-prerequisites.md.txt)