Personalizar imágenes de contenedor

Las imágenes base preconfiguradas que proporciona Cloud Workstations solo contienen un entorno mínimo con IDE, terminal de Linux básica y herramientas de lenguaje, y un servidor de sshd. Para acelerar la configuración del entorno de casos de uso de desarrollo específicos, puedes crear imágenes de contenedor personalizadas que extiendan estas imágenes base para preinstalar herramientas y dependencias, y que ejecuten secuencias de comandos de automatización.

En el caso de las imágenes de contenedor personalizadas, te recomendamos configurar una canalización para volver a compilar estas imágenes de forma automática cuando se actualice la imagen base de Cloud Workstations, además de ejecutar una herramienta de análisis de contenedores, como Artifact Analysis, para inspeccionar las dependencias adicionales que agregaste. Eres responsable de mantener y actualizar los paquetes y las dependencias personalizados que se agregan a las imágenes personalizadas.

Antes de comenzar

1. Necesitas una máquina con herramientas para compilar imágenes de contenedor, como Docker, y para enviar imágenes a Artifact Registry con la Google Cloud CLI. Puedes usar Cloud Workstations o el editor de Cloud Shell para realizar estos pasos, que tienen estas herramientas preinstaladas.

2. Selecciona la imagen base que quieres usar de nuestra lista de imágenes base compatibles, como us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest.

   Como alternativa, puedes usar tu propia imagen de contenedor o usar imágenes de contenedor externas siguiendo las instrucciones para usar tu propia imagen de contenedor.

3. Crea una carpeta, como CUSTOM_IMAGE_FOLDER, y un Dockerfile dentro de esta carpeta que extienda la imagen base seleccionada, como se muestra en los ejemplos que aparecen a continuación.

Estructura de la imagen base de Cloud Workstations

Las imágenes base de Cloud Workstations comparten la siguiente estructura definida:

• El archivo de punto de entrada de la imagen base se establece en /google/scripts/entrypoint.sh.

• Durante el inicio, las imágenes base ejecutan archivos en /etc/workstation-startup.d/* en orden lexicográfico para inicializar el entorno de la estación de trabajo.

  Los archivos y su comportamiento son los siguientes:

  • 000_configure-docker.sh: Configura y ejecuta Docker dentro de la estación de trabajo.

  • 010_add-user.sh: Crea el usuario predeterminado en Cloud Workstations.

    Debido a que el disco persistente se conecta de forma dinámica al contenedor, los usuarios se deben agregar al inicio de la estación de trabajo, no en el Dockerfile.

  • 020_start-sshd.sh: Inicia el servicio sshd en el contenedor.

  • 030_customize-environment.sh: Ejecuta /home/user/.workstation/customize_environment como user.

  • 110_start-$IDE.sh: Inicia el IDE para la imagen.

• Cloud Workstations almacena imágenes de Docker en el directorio principal en /home/.docker_data para que las imágenes se conserven entre sesiones.

Para agregar funcionalidad adicional durante el inicio de la estación de trabajo, agrega tus secuencias de comandos en el directorio /etc/workstation-startup.d/:

• De forma predeterminada, las secuencias de comandos de este directorio se ejecutan como raíz. Para ejecutar las secuencias de comandos como un usuario diferente, usa el comando runuser.

• Debido a que las secuencias de comandos se ejecutan en orden lexicográfico, te recomendamos que antepongas un número de tres dígitos mayor que 200 a las secuencias de comandos.

Como alternativa, si no quieres extender una imagen de estaciones de trabajo, puedes crear una secuencia de comandos customize_environment en tu directorio principal.

Modificaciones del directorio principal

Cuando la configuración de la estación de trabajo especifica un directorio principal persistente (que es el comportamiento predeterminado), un disco persistente que respalda el directorio principal se conecta de forma dinámica al contenedor en el entorno de ejecución. Este proceso reemplaza las modificaciones realizadas en el directorio /home en el momento de la compilación de la imagen de contenedor.

Para conservar las actualizaciones, modifica el directorio /home en el entorno de ejecución del contenedor agregando una secuencia de comandos en el directorio /etc/workstation-startup.d o agregando una configuración por usuario en el directorio /etc/profile.d. Para acelerar el proceso, considera ejecutar la secuencia de comandos de configuración como un proceso en segundo plano (agrega un signo et, &, al final del comando) para evitar que se bloquee el inicio del contenedor.

Estos son algunos ejemplos de configuración del tiempo de compilación que se deben mover al entorno de ejecución del contenedor:

• Configuración de git por usuario
• Repositorios de git clonados en el directorio principal
• Configuración directa del usuario, como colocar archivos en un directorio $HOME/.config
• Creación de usuarios

Creación y modificación de usuarios

Debido a que el disco persistente se conecta de forma dinámica al contenedor durante el tiempo de ejecución, los usuarios se deben agregar al inicio de la estación de trabajo, no en el Dockerfile. Para modificar o crear usuarios adicionales, te recomendamos que actualices /etc/workstation-startup.d/010_add-user.sh o que crees tu propia secuencia de comandos que se ejecute durante el inicio.

Además, puedes modificar el perfil de Bash predeterminado para los usuarios actualizando los archivos en /etc/profile.d.

Actualiza las claves de Secure APT preconfiguradas

Las imágenes base de Cloud Workstations vienen preinstaladas con varias herramientas obtenidas de varios repositorios de terceros con Secure APT. Como parte del proceso de instalación, las claves públicas que proporcionan los propietarios del repositorio se importan con gpg y se colocan en archivos individuales en /usr/share/keyrings/. Se hace referencia a estos archivos desde los archivos list correspondientes en /etc/apt/sources.list.d/. Esto permite que apt verifique la integridad de un repositorio determinado cuando interactúa con él.

En ocasiones, los propietarios de repositorios de terceros pueden decidir cambiar la clave pública que se usa para validar la integridad de su repositorio, lo que hace que apt muestre un error cuando interactúa con él. Para resolver este problema potencial, puedes usar /google/scripts/refresh-preinstalled-apt-keys.sh, que obtiene las versiones más recientes de las claves públicas preinstaladas y las vuelve a importar.

También puedes ejecutar esta secuencia de comandos directamente en tu Dockerfile personalizado antes de ejecutar apt-get update:

# Refresh the preinstalled APT keys
RUN /google/scripts/refresh-preinstalled-apt-keys.sh

RUN apt-get update

Enumera las versiones instaladas del IDE

Varias imágenes base de Cloud Workstations vienen preinstaladas con un IDE. Para mayor comodidad, consulta la secuencia de comandos /google/scripts/preinstalled-ide-versions.sh incluida, que enumera el nombre y la información de la versión de los IDE instalados en la imagen.

Desactiva los privilegios de raíz de sudo

El usuario predeterminado de la estación de trabajo tiene privilegios de acceso raíz sudo en estos contenedores. Para desactivar el acceso raíz al contenedor de Docker, establece la variable de entorno CLOUD_WORKSTATIONS_CONFIG_DISABLE_SUDO en true cuando crees la configuración de la estación de trabajo.

Para establecer esta variable de entorno a través de la consola de Google Cloud cuando crees la configuración de tu estación de trabajo, sigue estos pasos:

1. Cuando crees la configuración de la estación de trabajo, completa la configuración de la información básica y de la máquina.
2. En el cuadro de diálogo Personalización del entorno, expande la sección Opciones avanzadas de contenedores y selecciona Variables de entorno.
3. Haz clic en addAgregar variable.
4. Ingresa CLOUD_WORKSTATIONS_CONFIG_DISABLE_SUDO y true como el valor.

Nota: Si un usuario puede salir del contenedor de Docker, es posible que pueda obtener privilegios de raíz en la VM subyacente.

Personaliza sin extender una imagen

Para mayor comodidad, todas las imágenes base de Cloud Workstations verifican la presencia de un archivo ejecutable ubicado en /home/user/.workstation/customize_environment y, si existe, lo ejecutan en segundo plano como user. Esto te permite ejecutar cualquier secuencia de comandos o objeto binario durante el inicio. A diferencia de .profile o .bashrc, la secuencia de comandos solo se ejecuta una vez cuando se inicia la estación de trabajo, en lugar de una vez por cada acceso a la shell.

Debido a que la secuencia de comandos customize_environment se ejecuta como user, asegúrate de actualizar los permisos según sea necesario cuando escribas la secuencia de comandos. Por ejemplo, si quieres instalar Emacs cada vez que se inicia tu estación de trabajo, el contenido de customize_environment podría ser similar al siguiente:

#!/bin/bash
sudo apt-get update
sudo apt-get install -y emacs

Los registros de ejecución de customize_environment se pueden encontrar en el contenedor en /var/log/customize_environment y también se escriben en los registros de salida del contenedor. Cuando se ejecuta correctamente customize_environment, se crea un archivo en /var/run/customize_environment_done. Debido a que customize_environment se ejecuta en paralelo con el inicio de la estación de trabajo, los paquetes que instala la secuencia de comandos pueden estar disponibles unos momentos después de que se inicie la estación de trabajo.

Evita los tiempos de espera de inactividad

Para mayor comodidad, todas las imágenes base de Cloud Workstations incluyen una secuencia de comandos preinstalada en /google/scripts/keep_alive.sh. Esta secuencia de comandos envía mensajes de keep-alive regulares, que pueden evitar que la estación de trabajo se cierre debido a tiempos de espera de inactividad cuando ejecutas procesos en segundo plano sin interacción directa.

Evita los tiempos de espera de inactividad con agentes de IA

Además, las imágenes base de Cloud Workstations incluyen secuencias de comandos de configuración de agentes de muestra en /google/samples/agents/keepalive/. Estos parámetros de configuración de ejemplo te permiten configurar agentes de programación de IA (como Claude Code y la CLI de Antigravity) dentro de la estación de trabajo para mantenerla activa automáticamente mientras trabajan en tareas. Cuando el agente finaliza sus tareas o se detiene para esperar la entrada del usuario, la secuencia de comandos deja de enviar mensajes de keep-alive, lo que permite que la estación de trabajo agote el tiempo de espera debido a la inactividad. Estas configuraciones funcionan mejor cuando la configuración de la estación de trabajo se establece para usar la suspensión de la estación de trabajo (idleAction establecido en SUSPEND), lo que permite que la estación de trabajo guarde el estado de la memoria y se reanude sin problemas cuando regreses.

Para obtener más información sobre cómo configurar flujos de trabajo asistidos por agentes y hooks de keep-alive, consulta Desarrollo optimizado para agentes.

Usa tu propia imagen de contenedor

También puedes usar tu propia imagen de contenedor o imágenes de contenedor externas, siempre que estén basadas en Linux y ejecuten un proceso de bloqueo cuando se inicie el contenedor.

Cuando configures el Dockerfile, la instrucción ENTRYPOINT debe ejecutar un proceso de bloqueo, como sleep infinity, para que el contenedor siga ejecutándose, en lugar de salir de inmediato. Como alternativa, en la configuración de la estación de trabajo, puedes establecer el campo config.container.args para especificar un proceso de bloqueo.

Cuando uses tu propia imagen de contenedor, ten en cuenta lo siguiente:

• Cloud Workstations no requiere secuencias de comandos adicionales de la imagen base de Cloud Workstations.

  Sin embargo, puedes ver las secuencias de comandos en el directorio /etc/workstation-startup.d/ dentro de un contenedor que ejecuta la imagen base de Cloud Workstations. Los nombres de los archivos indican lo que hace cada secuencia de comandos.

• Te recomendamos que ejecutes un servidor SSH en el puerto 22 para que puedas conectarte con el comando gcloud workstations ssh, los túneles SSH o los IDE locales. Para obtener instrucciones de configuración, consulta Configura un servidor SSH en tu propia imagen de contenedor.

• Te recomendamos que ejecutes tu IDE o servidor web predeterminado en el puerto 80.

Google Cloud proporciona imágenes base estándar que puedes usar para compilar una imagen de contenedor completamente personalizada.

Configura un servidor SSH en tu propia imagen de contenedor

El puerto del contenedor 22 no se expone directamente a Internet ni a tu red de VPC. Cuando ejecutas gcloud workstations ssh, Cloud Workstations autentica tus credenciales de la CLI de gcloud y verifica los permisos de Identity and Access Management (IAM) para generar un token de acceso de corta duración. La puerta de enlace de la estación de trabajo verifica este token antes de reenviar el tráfico del túnel al puerto 22 del contenedor. Para usar un puerto SSH personalizado, consulta Usa servidores SSH en puertos diferentes.

Debido a que la puerta de enlace ya autentica las conexiones y gcloud workstations ssh no sube claves SSH, configura sshd para que acepte contraseñas vacías y borra la contraseña del usuario de destino. De lo contrario, gcloud workstations ssh falla o solicita una contraseña. En la imagen base preconfigurada, SSH se configura en /etc/ssh/sshd_config, /etc/workstation-startup.d/010_add-user.sh y /etc/workstation-startup.d/020_start-sshd.sh. Las imágenes personalizadas compiladas desde cero no ejecutan automáticamente secuencias de comandos en /etc/workstation-startup.d/, por lo que debes ejecutar los comandos de inicio desde la secuencia de comandos ENTRYPOINT del contenedor.

Para configurar SSH en tu imagen de contenedor, completa los siguientes pasos:

1. En tu Dockerfile, instala openssh-server y sudo, y quita cualquier clave de host SSH de tiempo de compilación en la misma capa de RUN. Quitar estas claves evita que se incorporen claves privadas en la imagen para que cada estación de trabajo pueda generar claves únicas durante el inicio. Por ejemplo, en Debian o Ubuntu, agrega la siguiente instrucción:

   RUN apt-get update && \
       apt-get install -y --no-install-recommends openssh-server sudo && \
       apt-get clean && \
       rm -rf /var/lib/apt/lists/* /etc/ssh/ssh_host_*
   

2. Configura /etc/ssh/sshd_config en el momento de la compilación para permitir contraseñas vacías y habilitar el subsistema sftp para transferencias de archivos y los IDE locales, como JetBrains Gateway:

   PasswordAuthentication yes
   PermitEmptyPasswords yes
   PrintLastLog no
   PrintMotd no
   PubkeyAuthentication no
   Subsystem sftp /usr/lib/openssh/sftp-server
   TCPKeepAlive no
   UsePAM yes
   

   Si /etc/ssh/sshd_config incluye archivos de inserción en /etc/ssh/sshd_config.d/ que configuran PasswordAuthentication no, actualiza o quita esos archivos para que no anulen /etc/ssh/sshd_config.

3. En la secuencia de comandos ENTRYPOINT de tu contenedor, crea la cuenta user (UID 1000) y borra su contraseña. De forma predeterminada, gcloud workstations ssh se conecta como user. Crea esta cuenta durante el inicio en lugar de en tu Dockerfile, ya que Cloud Workstations activa /home de forma dinámica en el entorno de ejecución cuando usas un directorio principal persistente:

   #!/bin/bash
   userid=1000
   userdel "$(id -nu "$userid" 2>/dev/null)" 2>/dev/null || true
   groups=sudo,users
   if [ "${CLOUD_WORKSTATIONS_CONFIG_DISABLE_SUDO:-false}" == "true" ]; then
     groups=users
   fi
   useradd -m user -u $userid -G $groups --shell /bin/bash > /dev/null
   passwd -d user > /dev/null
   echo "%sudo ALL=NOPASSWD: ALL" >> /etc/sudoers
   

4. En la secuencia de comandos ENTRYPOINT de tu contenedor, genera claves de host SSH en /etc/ssh/, crea /run/sshd y, luego, inicia /usr/sbin/sshd en el puerto 22:

   #!/bin/bash
   echo "Generating host SSH keys"
   yes | ssh-keygen -q -f /etc/ssh/ssh_host_rsa_key -t rsa \
       -C 'host' -N '' > /dev/null
   yes | ssh-keygen -q -f /etc/ssh/ssh_host_ecdsa_key -t ecdsa \
       -C 'host' -N '' > /dev/null
   yes | ssh-keygen -q -f /etc/ssh/ssh_host_ed25519_key -t ed25519 \
       -C 'host' -N '' > /dev/null
   
   echo "Starting sshd"
   mkdir -p /run/sshd
   
   # Send sshd logs to container output logs.
   /usr/sbin/sshd -D -e &
   

   Si la secuencia de comandos ENTRYPOINT de tu contenedor no ejecuta otro proceso en primer plano, omite & y ejecuta exec /usr/sbin/sshd -D -e como el proceso en primer plano.

Extiende las imágenes base de Cloud Workstations

Cuando extiendes una imagen base de Cloud Workstations para crear una imagen personalizada para tu entorno de estación de trabajo, puedes adoptar tres enfoques:

1. Actualiza tu Dockerfile para incluir cualquier recurso estático adicional que desees agregar.
2. Agrega archivos ejecutables adicionales en /etc/workstation-startup.d/ para personalizar el contenedor en ejecución. Los archivos de este directorio se ejecutan automáticamente en orden lexicográfico cuando se inicia el contenedor, por lo que puedes agregar un prefijo al nombre del archivo para ejecutarlo en el momento adecuado durante el inicio de la estación de trabajo.
3. Anula el ENTRYPOINT en tu Dockerfile para personalizar por completo el inicio del contenedor.

Nota: Cualquier modificación del usuario debe realizarse en el entorno de ejecución del contenedor, no en el Dockerfile. Esto se debe a que /home se activa de forma dinámica en el contenedor en el momento del inicio.

Dockerfiles personalizados de muestra

En esta sección, se proporcionan situaciones de ejemplo y las instrucciones para crear tus propios Dockerfiles.

Imagen de contenedor con emacs preinstalado

Para crear una imagen de contenedor con emacs preinstalado, ejecuta los siguientes comandos:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

RUN sudo apt update
RUN sudo apt install -y emacs

Imagen de contenedor con personalización del usuario

Sigue estos pasos para personalizar una imagen de contenedor:

1. Crea una secuencia de comandos en /etc/workstation-startup.d/* que se ejecute después de 010_add-user.sh, por ejemplo, 011_customize-user.sh:

   #!/bin/bash
   # Create new group
   groupadd $GROUP
   # Add the user to a new group
   usermod -a -G $GROUP $USERNAME
   

   Reemplaza $GROUP por el nombre del grupo nuevo y $USERNAME por el nombre de usuario.

2. Suponiendo que asignaste el nombre 011_customize-user.sh a tu secuencia de comandos, agrega lo siguiente a tu imagen en tu Dockerfile y haz que sea ejecutable:

   FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest
   
   COPY 011_customize-user.sh /etc/workstation-startup.d/
   
   RUN chmod +x /etc/workstation-startup.d/011_customize-user.sh
   

Imagen de contenedor que establece variables de entorno de contenedor en sesiones de SSH

Las variables de entorno establecidas en la configuración de la estación de trabajo o en el nivel de la estación de trabajo se pasan a los subprocesos directos con el comando de punto de entrada. Esto incluye el IDE en las imágenes base preconfiguradas. Sin embargo, las sesiones de SSH no son procesos secundarios del punto de entrada y no tienen configuradas estas variables de entorno personalizadas.

Para establecer esas variables de entorno en las sesiones de SSH, configura una imagen de contenedor personalizada que retransmita estas variables de entorno desde el comando de punto de entrada del contenedor al archivo /etc/environment.

Para ello, sigue estos pasos:

1. Crea una secuencia de comandos en /etc/workstation-startup.d/* que se ejecute después de 010_add-user.sh, por ejemplo, 011_add-ssh-env-variables.sh:

   #!/bin/bash
   #
   echo "CUSTOM_ENV_VAR=$CUSTOM_ENV_VAR" >> /etc/environment
   

   Reemplaza CUSTOM_ENV_VAR por el nombre de la variable de entorno previsto.

2. Suponiendo que asignaste el nombre 011_add-ssh-env-variables.sh a tu secuencia de comandos, agrega lo siguiente a tu imagen en tu Dockerfile y haz que sea ejecutable:

   FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest
   
   COPY 011_add-ssh-env-variables.sh /etc/workstation-startup.d/
   
   RUN chmod +x /etc/workstation-startup.d/011_add-ssh-env-variables.sh
   

Imagen de contenedor que habilita el reenvío de X11 para sesiones de SSH

El reenvío de X11 te permite iniciar aplicaciones remotas y reenviar la pantalla de la aplicación a una máquina local.

Para crear una imagen de contenedor que habilite el reenvío de X11, modifica el archivo de configuración del daemon de OpenSSH (/etc/ssh/sshd_config) que proporcionan las imágenes base de Cloud Workstations agregando X11Forwarding yes (para permitir el reenvío de X11) y AddressFamily inet (para garantizar que solo se use IPv4). Para obtener más información sobre estas palabras clave, consulta las páginas web de OpenBSD sobre AddressFamily y X11Forwarding.

Este es un Dockerfile de ejemplo, que realiza las modificaciones necesarias:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

# Permit X11 forwarding using only IPv4
RUN cat >> /etc/ssh/sshd_config <<-EOF

AddressFamily inet
X11Forwarding yes
EOF

Copia Code OSS para Cloud Workstations en otra imagen de contenedor

Una compilación de varias etapas te permite usar varias declaraciones FROM en tu Dockerfile. Cada instrucción FROM puede usar una base diferente y permite copiar artefactos entre las etapas de compilación. Para agregar Code OSS para Cloud Workstations a otra imagen de contenedor, usa una compilación de varias etapas para copiar la carpeta de la aplicación /opt/code-oss en tu imagen. Si deseas iniciar Code OSS para Cloud Workstations en el momento de inicio del contenedor, copia también la secuencia de comandos /etc/workstation-startup.d/110_start-code-oss.sh en tu contenedor.

Este es un Dockerfile de ejemplo que copia Code OSS en la imagen de JetBrains IntelliJ Ultimate. Luego, puedes interactuar con cualquiera de los IDE:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest as code-oss-image

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/jetbrains-intellij:latest

# Copy Code OSS for Cloud Workstations and startup scripts into our custom image
COPY --from=code-oss-image /opt/code-oss /opt/code-oss
COPY --from=code-oss-image /etc/workstation-startup.d/110_start-code-oss.sh /etc/workstation-startup.d/110_start-code-oss.sh

# Use the existing entrypoint script which will execute all scripts in /etc/workstation-startup.d/
ENTRYPOINT ["/google/scripts/entrypoint.sh"]

Imagen de contenedor que preinstala extensiones de IDE en Code OSS para Cloud Workstations para el desarrollo de Java

Para crear una imagen de contenedor que preinstale extensiones de IDE en Code OSS para Cloud Workstations para el desarrollo de Java en el momento de la compilación, ejecuta los siguientes comandos:

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

RUN wget https://open-vsx.org/api/vscjava/vscode-java-debug/0.40.1/file/vscjava.vscode-java-debug-0.40.1.vsix && \
unzip vscjava.vscode-java-debug-0.40.1.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-debug

RUN wget https://open-vsx.org/api/vscjava/vscode-java-dependency/0.19.1/file/vscjava.vscode-java-dependency-0.19.1.vsix && \
unzip vscjava.vscode-java-dependency-0.19.1.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-dependency

RUN wget https://open-vsx.org/api/redhat/java/1.6.0/file/redhat.java-1.6.0.vsix && \
unzip redhat.java-1.6.0.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/redhat-java

RUN wget https://open-vsx.org/api/vscjava/vscode-maven/0.35.2/file/vscjava.vscode-maven-0.35.2.vsix && \
unzip vscjava.vscode-maven-0.35.2.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-maven

RUN wget https://open-vsx.org/api/vscjava/vscode-java-test/0.35.0/file/vscjava.vscode-java-test-0.35.0.vsix && \
unzip vscjava.vscode-java-test-0.35.0.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-test

RUN chmod a+rwx -R /opt/code-oss/extensions/

Si preinstalas extensiones, se consideran extensiones integradas. No podrás actualizar estas extensiones y es posible que no aparezcan en la sección de instaladas en Extensions Marketplace. Sin embargo, puedes encontrar tus extensiones integradas buscando @builtin.

Otra forma de instalar extensiones en el inicio es ejecutar una secuencia de comandos de inicio. Por ejemplo, incluye la siguiente secuencia de comandos de inicio en /etc/workstation-startup.d/120_install_extensions.sh:

sudo -u user /opt/code-oss/bin/codeoss-cloudworkstations --install-extension vscjava.vscode-java-debug@0.40.1 \
--install-extension vscjava.vscode-java-dependency@0.19.1  \
--install-extension redhat.java@1.6.0 \
--install-extension vscjava.vscode-maven@0.35.2 \
--install-extension vscjava.vscode-java-test@0.35.0

Con este método, la extensión aparece en Extensions Marketplace y puedes actualizarla desde allí.

Nota: También puedes descargar previamente tus archivos VSIX en el momento de la compilación y usarlos en el entorno de ejecución para obtener protección adicional y mejorar el rendimiento de inicio.

Instala IDE y complementos de JetBrains en imágenes base

Cuando personalizas imágenes de Docker para las configuraciones de las estaciones de trabajo, puedes instalar IDE y complementos de JetBrains, como Cloud Code para IntelliJ, en la imagen base. Las imágenes base de Cloud Workstations para los productos de JetBrains incluyen las siguientes secuencias de comandos para ayudarte:

• jetbrains-installer.sh: Instala los IDE de JetBrains
• plugin-installer.sh: Instala complementos, como Cloud Code para IntelliJ.

Usa estas secuencias de comandos según sea necesario para personalizar la imagen base, llamarlas con una secuencia de comandos de inicio o ejecutarlas después de iniciar la estación de trabajo.

Secuencias de comandos del instalador

Para ver los archivos de origen de las secuencias de comandos jetbrains-installer.sh y plugin-installer.sh, inicia una estación de trabajo con una configuración que use una de las imágenes predefinidas de JetBrains, conéctate a la estación de trabajo a través de JetBrains Gateway o SSH y, luego, explora los archivos de secuencia de comandos en el directorio installer-scripts, que se encuentra en el directorio raíz.

Te recomendamos que ejecutes estas secuencias de comandos en el momento de la compilación del contenedor. Evita ejecutarlos en una estación de trabajo que ya se inició.

Usa la secuencia de comandos del instalador del complemento

La secuencia de comandos plugin-installer.sh usa la siguiente sintaxis:

plugin-installer.sh [-v VERSION] [-d DESTINATION-DIRECTORY] [-c CHECKSUM] [-f] PLUGIN_ID

Reemplaza lo siguiente:

• VERSION: Es el número de versión opcional del complemento que se instalará.
• DESTINATION-DIRECTORY: Es el directorio opcional en el que se debe instalar el complemento. Si no se especifica, se usa el directorio de trabajo.
• CHECKSUM: Es la suma de comprobación SHA-256 opcional del complemento solicitado.
• -f: Si se especifica, se reemplazará cualquier complemento existente.
• PLUGIN_ID: Es el identificador numérico obligatorio del complemento del Marketplace de JetBrains. Por ejemplo, para agregar Dart, usa 6351 como PLUGIN_ID. Para agregar Cloud Code para IntelliJ, usa 8079 como PLUGIN_ID.

Por ejemplo, para instalar la versión más reciente del complemento de Dart en IntelliJ, ejecuta el siguiente comando:

/installer-scripts/plugin-installer.sh -d /opt/ideaIU/plugins/ 6351

Usa la secuencia de comandos del instalador de JetBrains

Te recomendamos que uses la secuencia de comandos del instalador de JetBrains cuando extiendas una imagen base preconfigurada para los IDE de JetBrains.

La secuencia de comandos jetbrains-installer.sh usa la siguiente sintaxis:

jetbrains-installer.sh IDE [ pinned|latest ]

Reemplaza lo siguiente:

• IDE: el IDE de JetBrains que se instalará. Debes usar una de las siguientes abreviaturas de IDE:

  IDE	Se instaló el producto
  cl	CLion
  clion	CLion
  go	GoLand
  goland	GoLand
  iiu	Intellij Ultimate
  intellij	Intellij Ultimate
  pcp	PyCharm Professional
  pycharm	PyCharm Professional
  ps	PHPStorm
  phpstorm	PHPStorm
  rd	Rider
  rider	Rider
  rm	RubyMine
  rubymine	RubyMine
  ws	WebStorm
  webstorm	WebStorm

• pinned|latest: Opcional: Usa la versión fijada o la versión más reciente del IDE. La configuración predeterminada es latest.

Por ejemplo, para instalar la versión más reciente de Clion, ejecuta el siguiente comando:

/installer-scripts/jetbrains-installer.sh clion

Personaliza los archivos de configuración del IDE de JetBrains

Si se especifica un directorio principal persistente en la configuración de las estaciones de trabajo, las imágenes base de Cloud Workstations con IDE de JetBrains conservan automáticamente los archivos de configuración $IDE.vmoptions y $IDE.properties. Para anular la ubicación predeterminada de estos archivos, especifica la variable de entorno CLOUD_WORKSTATIONS_JETBRAINS_PERISTED_CONFIG_DIR.

Para obtener más información, consulta /etc/workstation-startup.d/120_persist-jetbrains-configs.sh en cualquier imagen base de JetBrains para saber cómo Cloud Workstations configura esto de forma predeterminada.

Extiende una imagen de Docker base con Cloud Code para IntelliJ

En el siguiente fragmento de Dockerfile, se extiende una imagen de Docker base con Cloud Code para IntelliJ, ya que se incluye 8079 como el identificador de complemento requerido. En el ejemplo, también se especifica de forma opcional version 22.9.3-222 como el número de versión, /opt/ideaIU/plugins/ como el directorio de destino y 89628279ed9042c526a81facc09bf53f8fb8b83b4595b0d329d94c1611e0c379 como la suma de comprobación:

...
# Install IDE and Plugins
RUN bash /installer-scripts/jetbrains-installer.sh intellij pinned && \
  # Install Cloud Code - https://plugins.jetbrains.com/plugin/8079-cloud-code
  bash /installer-scripts/plugin-installer.sh \
      -v 22.9.3-222 \
      -d /opt/ideaIU/plugins/ \
      -c 89628279ed9042c526a81facc09bf53f8fb8b83b4595b0d329d94c1611e0c379 \
      8079

# Register IDE with JetBrains Gateway
RUN echo 'runuser user -c "/opt/ideaIU/bin/remote-dev-server.sh registerBackendLocationForGateway"' > /etc/workstation-startup.d/110_register-intellij-with-gateway.sh \
    echo 'echo "IntelliJ-Ultimate ready for incoming gateway connection"' >> /etc/workstation-startup.d/110_register-intellij-with-gateway.sh
...

Instala extensiones de IDE adicionales en Code OSS para Cloud Workstations

Encuentra extensiones de IDE adicionales en el Registro abierto de VSX. También puedes encontrar la URL del archivo .vsix copiando la URL del vínculo Descargar de cualquier extensión.

Si abres el Extensions Marketplace de desde una estación de trabajo, aparecerá Instalar en lugar de Descargar.

Configuración predeterminada de Code OSS para Cloud Workstations

Para obtener información detallada sobre el almacenamiento de la configuración en Code OSS para Cloud Workstations, consulta Personaliza la configuración.

Si especificas un directorio principal persistente en la configuración de las estaciones de trabajo, puedes establecer la configuración predeterminada de Code OSS para Cloud Workstations agregando un secuencia de comandos de inicio que escriba la configuración en $HOME/.codeoss-cloudworkstations/data/Machine/settings.json.

Por ejemplo, si deseas establecer el tema de color predeterminado en Oscuro, extiende la imagen del editor base para incluir la siguiente secuencia de comandos en /etc/workstation-startup.d/150_default-ide-color-theme.sh

cat <<< $(jq '. += {"workbench.colorTheme": "Default Dark Modern"}' settings.json) > settings.json

Compila una imagen de contenedor personalizada

Para obtener información detallada sobre los comandos de Docker, consulta la referencia de Docker. Ingresa el siguiente comando para compilar tu contenedor:

docker build CUSTOM_IMAGE_FOLDER -t TARGET_IMAGE

Ten en cuenta que, si reemplazas el texto que precede al ícono de edición Editar, se actualizarán los demás ejemplos de esta página.

Reemplaza lo siguiente:

• CUSTOM_IMAGE_FOLDER: Es la ruta de acceso a la carpeta que creaste para almacenar tu imagen personalizada.

• TARGET_IMAGE: Es la ruta de acceso a tu imagen en Artifact Registry.

  Por ejemplo, TARGET_IMAGE podría apuntar a una ruta de imagen de destino similar a la siguiente:

  *.pkg.dev/cloud-workstations-external/customimage:latest
  

  Reemplaza * según sea necesario por el nombre de la región y cualquier identificador adicional.

También puedes actualizar la variable de entorno CLOUD_WORKSTATIONS_CUSTOM_IMAGE para que apunte al repositorio.

Para obtener más información sobre cómo almacenar imágenes de Docker en Artifact Registry, consulta las siguientes secciones:

• Cómo crear un repositorio de Docker con Artifact Registry.
• Convenciones de nombres para nombres de repositorios y de imágenes.

Aloja tu imagen de contenedor personalizada

Para alojar imágenes de contenedor personalizadas, recomendamos y admitimos Artifact Registry. Si usas GitHub o cualquier otro repositorio público o privado, es posible que Cloud Workstations no funcione como se espera. Para obtener más información, consulta la nota importante en la sección Usa una imagen de contenedor personalizada.

Prueba tu imagen de contenedor personalizada

Una vez que se complete la compilación del contenedor, puedes probarlo con el siguiente comando:

docker run --privileged -p LOCAL_PORT:CONTAINER_PORT TARGET_IMAGE

Reemplaza lo siguiente:

• LOCAL_PORT: el número de puerto local
• CONTAINER_PORT: Es el número de puerto del contenedor.

Por ejemplo, si reemplazas LOCAL_PORT:CONTAINER_PORT por 8080:80, se asigna el puerto 8080 para usarlo de forma local y el puerto 80 para usarlo en el contenedor.

Si extiendes la imagen del editor base de Cloud Workstations, ejecuta el comando docker y, luego, prueba la imagen de la estación de trabajo conectándote a ella a través de tu navegador local o ejecutando ssh para conectarte a tu contenedor:

• Si te conectas a través del navegador, asegúrate de pasar -p 8080:80 a tu comando docker run y, luego, abre localhost:8080.
• Si prefieres conectarte a través de SSH, asegúrate de pasar -p 2222:22 a tu comando docker run y, luego, ejecuta ssh user@localhost -p 2222.

Usa una imagen de contenedor personalizada

Para usar tu imagen de contenedor personalizada después de compilarla y probarla de forma local, envía el contenedor a Artifact Registry con el siguiente comando:

docker push TARGET_IMAGE

Ahora puedes crear una configuración de estación de trabajo con la imagen de contenedor que acabas de crear y enviar.

Importante: Si tu imagen se aloja en un repositorio privado, asegúrate de que la configuración de tu estación de trabajo también especifique una cuenta de servicio que tenga permisos de extracción en el repositorio.

Para obtener más información, consulta Crea un repositorio de Docker con Artifact Registry.

Depurar problemas

Para encontrar y depurar problemas que se producen cuando se ejecuta la imagen de contenedor, revisa los registros de salida del contenedor de las estaciones de trabajo en ejecución.

Recomendación: Protege tu canalización de imágenes

Eres responsable de mantener y actualizar los paquetes y las dependencias personalizados que se agreguen a las imágenes personalizadas.

Si creas imágenes personalizadas, te recomendamos lo siguiente:

• Ejecuta una herramienta de análisis de contenedores, como Artifact Analysis, para inspeccionar las dependencias adicionales que agregaste.
• Programa compilaciones para volver a compilar imágenes semanalmente o aprende a automatizar las recompilaciones de imágenes de contenedor.

¿Qué sigue?

• Automatiza las recompilaciones de imágenes de contenedor para sincronizar las actualizaciones de imágenes base con Cloud Build y Cloud Scheduler.
• Configura las prácticas recomendadas de seguridad.
• Obtén más información sobre Artifact Analysis.