Tutorial: Implementación en un clúster de Service Fabric

Artículo
06/08/2023

En este tutorial se explican varias formas posibles de configurar el entorno de Jenkins, así como diferentes maneras de implementar la aplicación en un clúster de Service Fabric después de que se ha creado. Siga estos pasos generales para configurar correctamente Jenkins, incorporar los cambios de GitHub, compilar la aplicación e implementarla en el clúster:

Asegúrese de instalar los requisitos previos.
A continuación, siga los pasos descritos en una de estas secciones para configurar Jenkins:
Después de configurar Jenkins, siga los pasos de la sección Creación y configuración de trabajos de Jenkins para configurar GitHub de forma que se desencadene Jenkins cuando se realicen cambios en la aplicación y para configurar la canalización de trabajos de Jenkins mediante el paso de compilación para incorporar los cambios desde GitHub y compilar la aplicación.
Por último, configure el paso posterior a la compilación de trabajos de Jenkins para implementar la aplicación en el clúster de Service Fabric. Hay dos maneras de configurar Jenkins para implementar la aplicación en un clúster:
- En entornos de desarrollo y pruebas, use Configuración de la implementación mediante el punto de conexión de administración de clúster. Este es el método de implementación más sencillo de configurar.
- En entornos de producción, use Configuración de la implementación mediante las credenciales de Azure. Microsoft recomienda este método para los entornos de producción porque con las credenciales de Azure puede limitar el acceso que un trabajo de Jenkins tiene a los recursos de Azure.

Requisitos previos

Asegúrese de que Git esté instalado localmente. La versión adecuada de Git se puede instalar desde la página de descargas de la Git, en función de su sistema operativo. Si no conoce Git, encontrará más información al respecto en la documentación de Git.
En este artículo se usa el ejemplo de introducción a Service Fabric de GitHub: https://github.com/Azure-Samples/service-fabric-java-getting-started para compilar e implementar la aplicación. Puede bifurcar este repositorio para seguir el tutorial, o bien, con algunas modificaciones en las instrucciones, usar su propio proyecto de GitHub.

Instalación del complemento de Service Fabric en un entorno existente de Jenkins

Si va a agregar el complemento de Service Fabric a un entorno existente de Jenkins, tiene que seguir estos pasos:

CLI de Service Fabric (sfctl). Instale la CLI en el nivel de sistema en lugar de en el nivel de usuario, de modo que Jenkins pueda ejecutar los comandos de la CLI.
Para implementar aplicaciones de Java, instale Gradle y Open JDK 8.0.
Para implementar aplicaciones .NET Core 2.0, instale el SDK de .NET Core 2.0.

Después de instalar los requisitos previos necesarios para su entorno, puede buscar el complemento de Azure Service Fabric en el Marketplace de Jenkins e instalarlo.

Una vez instalado el complemento, vaya directamente a Creación y configuración de trabajos de Jenkins.

Configuración de Jenkins en un clúster de Service Fabric

Jenkins se puede configurar dentro o fuera de un clúster de Service Fabric. En las secciones siguientes se muestra cómo configurarlo dentro de un clúster mientras se usa una cuenta de Azure Storage para guardar el estado de la instancia de contenedor.

Asegúrese de que tiene un clúster de Linux para Service Fabric con Docker instalado. Los clústeres de Service Fabric que se ejecutan en Azure ya tienen instalado Docker. Si ejecuta el clúster localmente (entorno de desarrollo de OneBox), compruebe si Docker está instalado en el equipo con el docker info comando . Si no está instalado, instálelo con los siguientes comandos:
```
sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh
```
Nota:

Asegúrese de que el puerto 8081 se especifica como punto de conexión personalizado en el clúster. Si usa un clúster local, asegúrese de que el puerto 8081 esté abierto en la máquina host y que tenga una dirección IP pública.

Clone la aplicación mediante los siguientes comandos:

git clone https://github.com/suhuruli/jenkins-container-application.git
cd jenkins-container-application

Guarde el estado del contenedor Jenkins en un recurso compartido de archivos:
1. Cree una cuenta de almacenamiento de Azure en la misma región que el clúster con un nombre como sfjenkinsstorage1.
2. Cree un recurso compartido de archivos en esa cuenta de almacenamiento con un nombre como sfjenkins.
3. Haga clic en Conectar para el recurso compartido de archivos y anote los valores que se muestran en Conectando desde Linux, valores que deberían ser parecidos a estos:
```
sudo mount -t cifs //sfjenkinsstorage1.file.core.windows.net/sfjenkins [mount point] -o vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777
```
Nota:

Para montar recursos compartidos cifs, debe tener instalado el paquete cifs-utils en los nodos del clúster.
Actualice los valores de marcador de posición en el script setupentrypoint.sh con los detalles de almacenamiento de Azure del paso 2.
```
vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
```
- Reemplace [REMOTE_FILE_SHARE_LOCATION] por el valor //sfjenkinsstorage1.file.core.windows.net/sfjenkins de la salida de la conexión en el paso 2 anterior.
- Reemplace [FILE_SHARE_CONNECT_OPTIONS_STRING] por el valor vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777 del paso 2 anterior.
Solo clúster seguro:

Para configurar la implementación de aplicaciones en un clúster seguro desde Jenkins, es necesario poder acceder al certificado del clúster en el contenedor de Jenkins. En el archivo ApplicationManifest.xml, en la etiqueta ContainerHostPolicies, agregue esta referencia de certificado y actualice el valor de huella digital con el del certificado del clúster.
```
<CertificateRef Name="MyCert" X509FindValue="[Thumbprint]"/>
```
Además, agregue las líneas siguientes en la etiqueta ApplicationManifest (raíz) en el archivo ApplicationManifest.xml y actualice el valor de huella digital con el del certificado del clúster.
```
<Certificates>
  <SecretsCertificate X509FindType="FindByThumbprint" X509FindValue="[Thumbprint]" />
</Certificates> 
```
Conéctese al clúster e instale la aplicación contenedora.

Clúster seguro
```
sfctl cluster select --endpoint https://PublicIPorFQDN:19080  --pem [Pem] --no-verify # cluster connect command
bash Scripts/install.sh
```
El comando anterior toma el certificado en formato PEM. Si el certificado está en formato PFX, puede usar el siguiente comando para convertirlo. Si su archivo PFX no está protegido con contraseña, especifique el parámetro passin como -passin pass:.
```
openssl pkcs12 -in cert.pfx -out cert.pem -nodes -passin pass:<password>
```
Clúster no seguro
```
sfctl cluster select --endpoint http://PublicIPorFQDN:19080 # cluster connect command
bash Scripts/install.sh
```
Así se instala un contenedor de Jenkins en el clúster y se puede supervisar mediante Service Fabric Explorer.

Nota:

La imagen Jenkins puede tardar un par de minutos en descargarse en el clúster.
En el explorador, vaya a http://PublicIPorFQDN:8081. Se proporciona la ruta de acceso de la contraseña de administrador inicial necesaria para iniciar sesión.
Observe Service Fabric Explorer para determinar en qué nodo se está ejecutando el contenedor Jenkins. Inicie una sesión de Secure Shell (SSH) en este nodo.
```
ssh user@PublicIPorFQDN -p [port]
```
Obtenga el identificador de la instancia del contenedor mediante docker ps -a.
Inicie una sesión de Secure Shell (SSH) en el contenedor y pegue la ruta de acceso que se mostró en el portal de Jenkins. Por ejemplo, si en el portal se muestra la ruta PATH_TO_INITIAL_ADMIN_PASSWORD, ejecute los siguientes comandos:
```
docker exec -t -i [first-four-digits-of-container-ID] /bin/bash   # This takes you inside Docker shell
```
```
cat PATH_TO_INITIAL_ADMIN_PASSWORD # This displays the password value
```
En la página de introducción de Jenkins, elija la opción Select plug-in to install (Seleccionar el complemento que se va a instalar), active la casilla None (Ninguno) y haga clic en Install (Instalar).
Cree un usuario o seleccione una opción para continuar como administrador.

Después de configurar Jenkins, vaya directamente a Creación y configuración de trabajos de Jenkins.

Configuración de Jenkins fuera de un clúster de Service Fabric

Jenkins se puede configurar dentro o fuera de un clúster de Service Fabric. En las secciones siguientes se muestra cómo se configura fuera de un clúster.

Asegúrese de que Docker está instalado en su máquina; para ello, ejecute docker info en el terminal. La salida indica si el servicio Docker se está ejecutando.

Si Docker no está instalado, ejecute los comandos siguientes:

sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh

Extraiga la imagen del contenedor de Jenkins de Service Fabric: docker pull rapatchi/jenkins:latest. Esta imagen lleva preinstalado el complemento de Jenkins de Service Fabric.
Ejecute la imagen del contenedor: docker run -itd -p 8080:8080 rapatchi/jenkins:latest
Obtenga el identificador de la instancia de la imagen de contenedor. Puede enumerar todos los contenedores de Docker con el comando docker ps –a
Inicie sesión en el portal de Jenkins con los siguientes pasos:
1. Inicie sesión en un shell de Jenkins desde el host. Use los cuatro primeros dígitos del identificador de contenedor. Por ejemplo, si el identificador de contenedor es 2d24a73b5964, use 2d24.
```
docker exec -it [first-four-digits-of-container-ID] /bin/bash
```
2. Desde el shell de Jenkins, obtenga la contraseña de administrador para la instancia del contenedor:
```
cat /var/jenkins_home/secrets/initialAdminPassword
```
3. Para iniciar sesión en el panel de Jenkins, abra la siguiente dirección URL en un explorador web: http://<HOST-IP>:8080. Use la contraseña del paso anterior para desbloquear Jenkins.
4. (Opcional). Después de iniciar sesión por primera vez, puede crear su propia cuenta de usuario y usarla para los pasos siguientes, o puede seguir usando la cuenta de administrador. Si crea un usuario, debe continuar con él.
Para configurar GitHub para que funcione con Jenkins, siga los pasos que se indican en Generating a new SSH key and adding it to the SSH agent (Generación de una clave SSH nueva y su adición al agente de SSH).
- Use las instrucciones que proporciona GitHub para generar la clave SSH y agregar la clave SSH a la cuenta de GitHub que hospeda el repositorio.
- Ejecute los comandos que se mencionan en el vínculo anterior en el shell de Docker para Jenkins (no en el host).
- Para iniciar sesión en el shell de Jenkins desde un host, use el siguiente comando:
```
docker exec -t -i [first-four-digits-of-container-ID] /bin/bash
```

Asegúrese de que el clúster o la máquina donde se hospeda la imagen del contenedor de Jenkins tengan una dirección IP pública. Esto permite a la instancia de Jenkins recibir notificaciones de GitHub.

Después de configurar Jenkins, continúe con la siguiente sección, Creación y configuración de trabajos de Jenkins.

Creación y configuración de trabajos de Jenkins

Los pasos descritos en esta sección muestran cómo configurar un trabajo de Jenkins para responder a los cambios en un repositorio de GitHub, capturar esos cambios y compilarlos. Al final de esta sección, se le dirige a los últimos pasos para configurar el trabajo para implementar la aplicación según si va a usar un entorno de desarrollo y pruebas o un entorno de producción.

En el panel de Jenkins, haga clic en New Item (Nuevo elemento).
Escriba un nombre para dicho elemento (por ejemplo, MyJob). Seleccione free-style project (proyecto de estilo libre) y haga clic en OK (Aceptar).
Se abre la página de configuración de trabajos. (Para obtener la configuración del panel de Jenkins, haga clic en el trabajo y, a continuación, haga clic en Configure [Configurar]).
En la pestaña General, marque la casilla GitHub project (Proyecto de GitHub) y especifique la dirección URL de su proyecto de GitHub. Dicha URL hospeda la aplicación de Java para Service Fabric que desea integrar con el flujo de integración continua e implementación continua (CI/CD) de Jenkins (por ejemplo, https://github.com/{your-github-account}/service-fabric-java-getting-started).
En la pestaña Source Code Management (Administración del código fuente) seleccione Git. Especifique la dirección URL del repositorio que hospeda la aplicación de Java para Service Fabric que desea integrar con el flujo de CI/CD de Jenkins (por ejemplo, https://github.com/{your-github-account}/service-fabric-java-getting-started). También puede especificar la rama que debe compilar (por ejemplo, /master).
Configure el repositorio de GitHub para que se comunique con Jenkins:
1. En la página del repositorio de GitHub, vaya a Settings> (Configuración) Integrations and Services (Integraciones y servicios).
2. Seleccione Add Service (Agregar servicio), escriba Jenkins y seleccione el complemento Jenkins-GitHub.
3. Escriba la dirección URL del webhook de Jenkins (de forma predeterminada, será http://<PublicIPorFQDN>:8081/github-webhook/). Haga clic en Add/Update Service (Agregar o actualizar servicio).
4. Se enviará un evento de prueba a la instancia de Jenkins. Debería ver una marca de verificación verde junto al webhook en GitHub y el proyecto se compilará.
En la pestaña Build Triggers (Compilar desencadenadores) de Jenkins, seleccione la opción de compilación que desea. En este ejemplo, va a desencadenar una compilación cada vez que se produce un incorporación de cambios en el repositorio, así que seleccione GitHub hook trigger for GITScm polling (Desencadenador de enlace de GitHub para el sondeo de GITScm). [antes, esta opción se denominaba Build when a change is pushed to GitHub (Compilar cuando se inserta un cambio en GitHub)].
En la pestaña Build (Compilar), realice una de las siguientes acciones según si va a compilar una aplicación Java o una .NET Core:
- Para aplicaciones Java: en la lista desplegable Add build step (Agregar paso de compilación), seleccione Invoke Gradle Script (Invocar script de Gradle). Haga clic en Avanzado. En el menú avanzado, especifique la ruta de acceso a Root build script (Script de compilación raíz) para la aplicación. Este toma el archivo build.gradle de la ruta de acceso especificada y funciona en consecuencia. Para la aplicación ActorCounter, esto es: ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter.
- Para las aplicaciones .NET Core: en la lista desplegable Add build step (Agregar paso de compilación), seleccione Execute Shell (Ejecutar Shell). En el cuadro de comando que aparece, primero debe cambiarse el directorio a la ruta de acceso donde se encuentra el archivo build.sh. Una vez cambiado el directorio, el script build.sh se puede ejecutar y compilará la aplicación.
```
cd /var/jenkins_home/workspace/[Job Name]/[Path to build.sh]  
./build.sh
```
  En la siguiente captura de pantalla se muestra un ejemplo de los comandos que se usan para compilar el ejemplo Counter Service con un nombre de trabajo de Jenkins CounterServiceApplication.
Para configurar Jenkins para implementar la aplicación en un clúster de Service Fabric en las acciones posteriores a la compilación, necesita la ubicación del certificado de ese clúster en el contenedor de Jenkins. Elija una de las siguientes, según si el contenedor de Jenkins se ejecuta dentro o fuera de su clúster, y tome nota de ella:
- Si Jenkins se ejecuta dentro del clúster: para encontrar la ruta de acceso al certificado, refleje el valor de la variable de entorno Certificates_JenkinsOnSF_Code_MyCert_PEM dentro del contenedor.
```
echo $Certificates_JenkinsOnSF_Code_MyCert_PEM
```
- Si Jenkins se ejecuta fuera de su clúster: siga estos pasos para copiar el certificado del clúster en el contenedor:
  1. El certificado debe estar en formato PEM. Si no tiene un archivo PEM, puede crear uno a partir del archivo PFX de certificado. Si su archivo PFX no está protegido con contraseña, ejecute el siguiente comando desde el host:
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:
```
    Si el archivo PFX está protegido con contraseña, incluya la contraseña en el parámetro -passin. Por ejemplo:
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:<password>
```
  2. Para obtener el identificador de contenedor para el contenedor de Jenkins, ejecute docker ps desde el host.
  3. Copie el archivo PEM en el contenedor con el siguiente comando de Docker:
```
docker cp clustercert.pem [first-four-digits-of-container-ID]:/var/jenkins_home
```

Ya casi hemos terminado. Mantenga abierto el trabajo de Jenkins. La última tarea consiste en configurar los pasos posteriores a la compilación para implementar la aplicación en el clúster de Service Fabric:

Para realizar la implementación en un entorno de desarrollo o de prueba, siga los pasos de la sección Configuración de la implementación mediante el punto de conexión de administración de clúster.
Para realizar la implementación en un entorno de producción, siga los pasos de la sección Configuración de la implementación mediante las credenciales de Azure.

Configuración de la implementación mediante el punto de conexión de administración de clúster

En entornos de desarrollo y pruebas, puede usar el punto de conexión de administración de clúster para implementar la aplicación. Para configurar la acción posterior a la compilación con el punto de conexión de administración de clúster para implementar la aplicación, apenas es necesario hacer nada. Si va a implementar en un entorno de producción, vaya directamente a Configuración de la implementación mediante credenciales de Azure para configurar una entidad de servicio de Microsoft Entra que se usará durante la implementación.

En el trabajo de Jenkins, haga clic en la pestaña Post-build Actions (Acciones posteriores a la compilación).
En la lista desplegable Post-Build Actions (Acciones posteriores a la compilación), seleccione Deploy Service Fabric Project (Implementar proyecto de Service Fabric).
En Service Fabric Cluster Configuration (Configuración del clúster de Service Fabric), seleccione el botón de radio Fill the Service Fabric Management Endpoint (Rellenar el punto de conexión de administración de Service Fabric).
En Management Host (Host de administración), escriba el punto de conexión de su clúster, por ejemplo {your-cluster}.eastus.cloudapp.azure.com.
En Client Key (Clave de cliente) y Client Cert (Certificado de cliente), escriba la ubicación del archivo PEM en el contenedor de Jenkins, por ejemplo /var/jenkins_home/clustercert.pem. (La ubicación del certificado la copió en el último paso de Creación y configuración de trabajos de Jenkins).
En Application Configuration (Configuración de la aplicación), configure los campos Application Name (Nombre de aplicación), Application Type (Tipo de aplicación) y Path to Application Manifest (Ruta de acceso al manifiesto de la aplicación) (relativa).
Haga clic en Verify configuration(Comprobar configuración). Tras la correcta comprobación, haga clic en Save (Guardar). La canalización del trabajo de Jenkins está ahora completamente configurada. Vaya directamente a Siguientes pasos para probar su implementación.

Configuración de la implementación mediante las credenciales de Azure

En entornos de producción, es muy recomendable configurar una credencial de Azure para implementar la aplicación. En esta sección se muestra cómo configurar una entidad de servicio de Microsoft Entra para usarla para implementar la aplicación en la acción posterior a la compilación. Puede asignar roles a entidades de servicio de su directorio para limitar los permisos del trabajo de Jenkins.

En entornos de desarrollo y pruebas, puede configurar las credenciales de Azure o el punto de conexión de administración de clúster para implementar la aplicación. Para más información sobre cómo configurar un punto de conexión de administración de clúster, consulte Configuración de la implementación mediante el punto de conexión de administración de clúster.

Para crear una entidad de servicio de Microsoft Entra y asignarle permisos en la suscripción de Azure, siga los pasos descritos en Uso del portal para crear una aplicación y una entidad de servicio de Microsoft Entra. Preste atención a lo siguiente:
- Mientras sigue los pasos descritos en el tema, asegúrese de copiar y guardar los valores siguientes: Id. de aplicación, Clave de aplicación, Id. de directorio (id. de inquilino) e Id. de suscripción. Los necesita para configurar las credenciales de Azure en Jenkins.
- Si no tiene los permisos necesarios sobre el directorio, deberá pedir al administrador que se los conceda o que le cree la entidad de servicio; o deberá configurar el punto de conexión de administración de su clúster en Post-Build Actions (Acciones posteriores a la compilación) para su trabajo en Jenkins.
- En la sección Crear una aplicación de Microsoft Entra, puede escribir cualquier dirección URL con formato correcto para la dirección URL de inicio de sesión.
- En la sección Asignación de aplicación a un rol, puede asignar a la aplicación el rol Lector en el grupo de recursos del clúster.
De nuevo en el trabajo de Jenkins, haga clic en la pestaña Post-build Actions (Acciones posteriores a la compilación).
En la lista desplegable Post-Build Actions (Acciones posteriores a la compilación), seleccione Deploy Service Fabric Project (Implementar proyecto de Service Fabric).
En Service Fabric Cluster Configuration (Configuración del clúster de Service Fabric), haga clic en Select the Service Fabric Cluster (Seleccionar el clúster de Service Fabric). Haga clic en Add (Agregar) junto a Azure Credentials (Credenciales de Azure). Haga clic en Jenkins para seleccionar el proveedor de credenciales de Jenkins.
En el proveedor de identidades de Jenkins, seleccione Microsoft Azure Service Principal (Entidad de servicio de Microsoft Azure) en la lista desplegable Kind (Variante).
Use los valores que guardó al configurar la entidad de servicio en el paso 1 para configurar los campos siguientes:
- Client ID (Id. de cliente): Id. de aplicación
- Client Secret (Secreto de cliente): Clave de aplicación
- Tenant ID (Id. de inquilino): Id. de directorio
- Subscription ID (Id. de suscripción): Id. de suscripción
Escriba un identificador descriptivo que use para seleccionar la credencial de Jenkins y una breve descripción. A continuación, haga clic en Verify Service Principal (Comprobar entidad de servicio). Si la comprobación es correcta, haga clic en Add (Agregar).
De nuevo en Service Fabric Cluster Configuration (Configuración del clúster de Service Fabric), asegúrese de que en Azure Credentials (Credenciales de Azure), se selecciona la nueva credencial.
En la lista desplegable Resource Group (Grupo de recursos), seleccione el grupo de recursos del clúster en el que quiere implementar la aplicación.
En la lista desplegable Service Fabric, seleccione el clúster en el que quiere implementar la aplicación.
En Client Key (Clave de cliente) y Client Cert (Certificado de cliente), escriba la ubicación del archivo PEM en el contenedor de Jenkins. Por ejemplo, /var/jenkins_home/clustercert.pem.
En Application Configuration (Configuración de la aplicación), configure los campos Application Name (Nombre de aplicación), Application Type (Tipo de aplicación) y Path to Application Manifest (Ruta de acceso al manifiesto de la aplicación) (relativa).
Haga clic en Verify configuration(Comprobar configuración). Tras la correcta comprobación, haga clic en Save (Guardar). La canalización del trabajo de Jenkins está ahora completamente configurada. Continúe con los Siguientes pasos para probar la implementación.

Solución de problemas del complemento de Jenkins

Si detecta algún error con el complemento de Jenkins, registre un problema en Jenkins JIRA para el componente específico.

Ideas para probar

GitHub y Jenkins ya están configurados. Considere la posibilidad de realizar algunos cambios de ejemplo en el proyecto reliable-services-actor-sample/Actors/ActorCounter en su bifurcación del repositorio, https://github.com/Azure-Samples/service-fabric-java-getting-started. Inserte los cambios en la rama master remota (o en cualquier rama que ha configurado para trabajar con ella). Esto desencadena el trabajo de Jenkins, MyJob, que ha configurado. Los cambios se capturan desde GitHub, se compilan y la aplicación se implementa en el clúster especificado en las acciones posteriores a la compilación.

Pasos siguientes

Jenkins en Azure