Guía de inicio rápido de Kf

En esta guía de inicio rápido, usarás un clúster de GKE, instalarás Kf y sus dependencias, y, luego, implementarás una aplicación de muestra de Cloud Foundry.

Antes de comenzar

Descripción general

  • Tu clúster de GKE debe cumplir con los siguientes requisitos:

    • Debe tener al menos cuatro nodos. Si necesitas agregar nodos, consulta Cambia el tamaño de un clúster.

    • El tipo de máquina mínimo debe tener al menos cuatro CPU virtuales, como e2-standard-4. Si el tipo de máquina del clúster no tiene al menos cuatro CPU virtuales, cámbialo como se describe en Migra cargas de trabajo a diferentes tipos de máquina.

    • De manera opcional, puedes inscribir el clúster en un canal de versiones. Te recomendamos que te inscribas en el canal de versiones regular, ya que otros se podrían basar en una versión de GKE que no es compatible con Kf. Sigue las instrucciones en Inscribe un clúster existente en un canal de versiones si tienes una versión estática de GKE.

    • Workload Identity debe estar habilitado.

    • Artifact Registry está habilitado.

    • Anthos Service Mesh (ASM).

    • Se instaló Tekton. Consulta la Matriz de dependencia para la versión.

    • Catálogo de servicios v0.3. Kf mantiene una versión personalizada del catálogo de servicios que le permite ejecutarse en versiones posteriores de Kubernetes.

    • Se requiere la CLI de Helm 3 para instalar el catálogo de servicios

    • Se debe contar con una cuenta de servicio de Google con la siguiente política de IAM (consulta el vínculo de instrucciones de creación a continuación):

      • roles/storage.admin
      • roles/iam.serviceAccountAdmin
      • serviceAccount:${CLUSTER_PROJECT}.svc.id.goog[kf/controller] (para el miembro serviceAccount:${CLUSTER_PROJECT}.svc.id.goog[kf/controller])

En la sección Limpiar, verás las instrucciones para borrar el clúster.

Habilita la compatibilidad con Compute Engine

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

    Ir a la página del selector de proyectos

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

  4. Habilita la API de Compute Engine.

    Habilita la API

Habilita y configura GKE

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

Establece la configuración de gcloud predeterminada mediante uno de los siguientes métodos:

  • Usa gcloud init si deseas ver una explicación sobre cómo configurar parámetros predeterminados.
  • Usa gcloud config para establecer el ID, la zona y la región del proyecto de manera individual.

Usa gcloud init

Si recibes el error One of [--zone, --region] must be supplied: Please specify location, completa esta sección.

  1. Ejecuta gcloud init y sigue las instrucciones:

    gcloud init

    Si usas SSH en un servidor remoto, usa la marca --console-only para evitar que el comando abra un navegador:

    gcloud init --console-only
  2. Sigue las instrucciones a fin de autorizar a gcloud para que use tu cuenta de Google Cloud.
  3. Crea una configuración nueva o selecciona una existente.
  4. Elige un proyecto de Google Cloud.
  5. Elige una zona predeterminada de Compute Engine.

Usa gcloud config

  • Establece tu ID del proyecto predeterminado:
    gcloud config set project project-id
  • Si trabajas con clústeres zonales, establece tu zona de procesamiento predeterminada:
    gcloud config set compute/zone compute-zone
  • Si trabajas con clústeres regionales, establece tu región de procesamiento predeterminada:
    gcloud config set compute/region compute-region
  • Actualiza gcloud a la versión más reciente:
    gcloud components update

Crea y prepara un clúster de GKE nuevo

Configura variables de entorno

export PROJECT_ID=YOUR_PROJECT_ID
export CLUSTER_PROJECT_ID=YOUR_PROJECT_ID
export CLUSTER_NAME=DESIRED_CLUSTER_NAME
export COMPUTE_ZONE=GCP_COMPUTE_ZONE (e.g. us-central1-a)
export COMPUTE_REGION=GCP_COMPUTE_REGION (e.g. us-central1)
export CLUSTER_LOCATION=${COMPUTE_ZONE}
export NODE_COUNT=NODE_COUNT (minimum is 4)
export MACHINE_TYPE=MACHINE_TYPE (e.g. e2-highmem-4)
export NETWORK=default (default is recommended)
export KF_VERSION=KF_VERSION (e.g. nightly, v1.0.2, or v1.0.3)

Configuración de la cuenta de servicio

Crea una cuenta de servicio de GCP (GSA) que se asociará a una cuenta de servicio de Kubernetes mediante Workload Identity. Esto evita la necesidad de crear e insertar una clave de cuenta de servicio.

  1. Crea la cuenta de servicio que usará Kf.

    gcloud iam service-accounts create ${CLUSTER_NAME}-sa \
        --project=${CLUSTER_PROJECT_ID} \
        --description="gcr.io admin for ${CLUSTER_NAME}" \
        --display-name="${CLUSTER_NAME}"
  2. Permite que la cuenta de servicio modifique su propia política. El controlador de Kf lo usará para agregar espacios (de nombres) nuevos a la política, lo que permite volver a usar Workload Identity.

    gcloud iam service-accounts add-iam-policy-binding ${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com \
      --project=${CLUSTER_PROJECT_ID} \
      --role="roles/iam.serviceAccountAdmin" \
      --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com"
  3. Otorga funciones a la cuenta de servicio para leer/escribir desde GCR.

    gcloud projects add-iam-policy-binding ${CLUSTER_PROJECT_ID} \
      --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
      --role="roles/storage.admin"
  4. Otorga la función de métricas de supervisión para el acceso de escritura a Cloud Monitoring.

    gcloud projects add-iam-policy-binding ${CLUSTER_PROJECT_ID} \
      --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
      --role="roles/monitoring.metricWriter"

Crea un clúster de GKE

gcloud container clusters create ${CLUSTER_NAME} \
--project=${CLUSTER_PROJECT_ID} \
--zone=${CLUSTER_LOCATION} \
--num-nodes=${NODE_COUNT} \
--machine-type=${MACHINE_TYPE} \
--network=${NETWORK} \
--addons=HttpLoadBalancing,HorizontalPodAutoscaling,NetworkPolicy \
--enable-stackdriver-kubernetes \
--enable-ip-alias \
--enable-network-policy \
--enable-autorepair \
--enable-autoupgrade \
--scopes=https://www.googleapis.com/auth/cloud-platform \
--release-channel=regular \
--workload-pool="${CLUSTER_PROJECT_ID}.svc.id.goog" \
--service-account="${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com"

Habilita Workload Identity

Ahora que tienes una cuenta de servicio y un clúster de GKE, asocia el espacio de nombres de identidad del clúster con el clúster.

gcloud iam service-accounts add-iam-policy-binding \
    "${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
    --project=${CLUSTER_PROJECT_ID} \
    --role="roles/iam.workloadIdentityUser" \
    --member="serviceAccount:${CLUSTER_PROJECT_ID}.svc.id.goog[kf/controller]"

Crea un clúster de GKE de destino

Configura el acceso a la línea de comandos de kubectl mediante el siguiente comando:

gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --project=${CLUSTER_PROJECT_ID} \
    --zone=${CLUSTER_LOCATION}

Crea un repositorio de Artifact Registry

  1. Crea un repositorio para las imágenes de contenedor que se almacenarán.

    gcloud beta artifacts repositories create ${CLUSTER_NAME} \
      --repository-format=docker \
      --location=${COMPUTE_REGION}
  2. Otorga permiso a la cuenta de servicio en el repositorio de Artifact Registry.

    gcloud beta artifacts repositories add-iam-policy-binding ${CLUSTER_NAME} \
      --location=${COMPUTE_REGION} \
      --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
      --role='roles/artifactregistry.writer'

Instala dependencias de software en el clúster

  1. Instala Anthos Service Mesh.

  2. Instala Tekton:

    kubectl apply -f https://github.com/tektoncd/pipeline/releases/download/v0.14.3/release.yaml
  3. Instala el catálogo de servicios:

    1. Copia service-catalog.tgz desde la carpeta del depósito de versiones.

      gsutil cp gs://kf-releases/${KF_VERSION}/service-catalog.tgz /tmp/service-catalog.tgz
    2. Descomprime el archivo.

      tar xf /tmp/service-catalog.tgz -C /tmp
    3. Crea espacios de nombres service-catalog

      kubectl create namespace service-catalog
    4. Usa Helm para actualizar el catálogo de servicios.

      helm upgrade service-catalog \
      /tmp/service-catalog/charts/catalog/ \
      --install \
      --namespace service-catalog \
      --values /tmp/service-catalog/values/catalog.yaml \
      --set image=gcr.io/kf-releases/service-catalog:${KF_VERSION}

Tu clúster está listo

Visita Realiza una limpieza cuando estés listo para borrar este clúster.

Instala Kf

  1. Consulta Crea y prepara un clúster de GKE para Kf a fin de crear un clúster preparado con el objetivo de ejecutar Kf.

  2. Selecciona la versión de Kf que quieras y anótala. Consulta la página Descargas de Kf para conocer las versiones disponibles.

  3. Instala CLI:

    Linux

    Esto instalará kf para todos los usuarios del sistema. Sigue las instrucciones de la pestaña de Cloud Shell para instalarlo tú mismo.

    gsutil cp gs://kf-releases/${KF_VERSION}/kf-linux /tmp/kf
    chmod a+x /tmp/kf
    sudo mv /tmp/kf /usr/local/bin/kf
    

    Mac

    Esto instalará kf para todos los usuarios del sistema.

    gsutil cp gs://kf-releases/${KF_VERSION}/kf-darwin /tmp/kf
    chmod a+x /tmp/kf
    sudo mv /tmp/kf /usr/local/bin/kf
    

    Cloud Shell

    Esto instalará kf en tu instancia de Cloud Shell si usas bash. Es posible que tengas que modificar las instrucciones para otros shells.

    mkdir -p ~/bin
    gsutil cp gs://kf-releases/${KF_VERSION}/kf-linux ~/bin/kf
    chmod a+x ~/bin/kf
    echo "export PATH=$HOME/bin:$PATH" >> ~/.bashrc
    source ~/.bashrc
    
  4. Instala los componentes del servidor:

    gsutil cp gs://kf-releases/${KF_VERSION}/kf.yaml /tmp/kf.yaml
    kubectl apply -f /tmp/kf.yaml
  5. Configura secretos:

    WI_ANNOTATION=iam.gke.io/gcp-service-account=${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com
    
    kubectl annotate serviceaccount controller ${WI_ANNOTATION} \
    --namespace kf \
    --overwrite
    
    echo "{\"apiVersion\":\"v1\",\"kind\":\"ConfigMap\",\"metadata\":{\"name\":\"config-secrets\", \"namespace\":\"kf\"},\"data\":{\"wi.googleServiceAccount\":\"${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com\"}}" | kubectl apply -f -
  6. Configura los valores predeterminados de Kf. Estos valores pueden modificarse más adelante. En el ejemplo siguiente, se usan plantillas de dominio con un proveedor de DNS comodín para proporcionar a cada espacio su propio nombre de dominio:

    export CONTAINER_REGISTRY=gcr.io/${CLUSTER_PROJECT_ID}
    export DOMAIN='$(SPACE_NAME).$(CLUSTER_INGRESS_IP).nip.io'
    
    kubectl patch configmaps config-defaults \
    -n=kf \
    -p="{\"data\":{\"spaceContainerRegistry\":\"${CONTAINER_REGISTRY}\",\"spaceClusterDomains\":\"- domain: ${DOMAIN}\"}}"
  7. Valida la instalación:

    kf doctor

Envía una aplicación

Requisitos

Para completar esta sección, se requiere lo siguiente:

  1. Kf debe estar instalado en un clúster de GKE compatible. Consulta Instala Kf para obtener instrucciones.
  2. De debe contar con un .kubeconfig orientado al clúster de Kf. Si creaste el clúster según las instrucciones de este documento, esto ya estará hecho. Puedes generar la configuración de forma explícita con gcloud container clusters get-credentials ${CLUSTER_NAME} --zone ${CLUSTER_LOCATION}.
  3. La CLI de kf debe estar instalada en tu ruta de acceso. Consulta Instala Kf para obtener instrucciones.
  4. La CLI de git debe estar instalada en tu ruta de acceso.

Prepara el espacio

  1. Crea un espacio nuevo:

    kf create-space test-space
  2. Orienta el espacio:

    kf target -s test-space

Envía la app de prueba de Cloud Foundry

  1. Clona el repositorio:

    git clone https://github.com/cloudfoundry-samples/test-app go-test-app
    cd go-test-app
  2. Envía la app:

    kf push test-app
  3. Busca la URL de la aplicación:

    1. Usa el formato de salida para recuperar solo la ruta:

      kf app test-app --output 'go-template={{index .status.routes }}'

    2. O lo siguiente para un enfoque de CF más tradicional:

      kf apps

  4. Abre la URL en tu navegador.

Limpia

Estos pasos deben quitar todos los componentes que creó la sección “Crea un clúster de GKE nuevo”.

  1. Borra el clúster de GKE:

    gcloud container clusters delete ${CLUSTER_NAME}
  2. Borra la cuenta de servicio de Google:

    gcloud iam service-accounts delete ${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com
  3. Borra las vinculaciones de políticas de IAM:

    gcloud projects remove-iam-policy-binding ${CLUSTER_PROJECT_ID} \
    --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/storage.admin"
    
    gcloud projects remove-iam-policy-binding ${CLUSTER_PROJECT_ID} \
    --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountAdmin"
    
    gcloud projects remove-iam-policy-binding ${CLUSTER_PROJECT_ID} \
    --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/monitoring.metricWriter"

Soluciona problemas

Errores de instalación

La dirección IP de Istio no está lista

Esto puede suceder si Istio demora un poco más de lo normal en obtener una IP externa. Es ideal que esperes un poco y vuelvas a ejecutar el paso de envío de Cloud Build. Sin embargo, es probable que suceda algo más.

Error: No se pudo encontrar Tiller

Si ves este error cuando instalas o actualizas el catálogo de servicios, actualiza la CLI de Helm a la versión 3.

ERROR DE ACTUALIZACIÓN: No se permiten los configmaps

Si ves este error cuando instalas o actualizas el catálogo de servicios, actualiza la CLI de Helm a la versión 3.

Error: UPGRADE FAILED: configmaps is forbidden: User "system:serviceaccount:kube-system:default" cannot list resource "configmaps" in API group "" in the namespace "kube-system"

Error del servidor (solicitud incorrecta): El carácter no es válido

Si ves este error cuando estableces los valores predeterminados de configuración, es probable que el valor de la variable de entorno ${DOMAIN} que se usa en el comando incluya un “$” de escape. Usa comillas simples para definir un dominio con un nombre de espacio o alguna otra alternativa:

Error from server (BadRequest): invalid character '$' in string escape code