Especificar recursos num manifesto de serviço
Descrição Geral
As aplicações e serviços do Service Fabric são definidos e com controlo de versões através de ficheiros de manifesto. Para obter uma descrição geral de nível superior do ServiceManifest.xml e ApplicationManifest.xml, veja Service Fabric application and service manifests (Manifestos de serviço e aplicações do Service Fabric).
O manifesto do serviço permite que os recursos utilizados pelo serviço sejam declarados ou alterados sem alterar o código compilado. O Service Fabric suporta a configuração de recursos de ponto final para o serviço. O acesso aos recursos especificados no manifesto do serviço pode ser controlado através do SecurityGroup no manifesto da aplicação. A declaração de recursos permite que estes recursos sejam alterados no momento da implementação, o que significa que o serviço não precisa de introduzir um novo mecanismo de configuração. A definição de esquema para o ficheiro ServiceManifest.xml é instalada com o SDK do Service Fabric e as ferramentas para C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd e está documentada na documentação do esquema ServiceFabricServiceModel.xsd.
Pontos Finais
Quando um recurso de ponto final é definido no manifesto de serviço, o Service Fabric atribui portas a partir do intervalo de portas da aplicação reservada quando uma porta não é especificada explicitamente. Por exemplo, observe o ponto final ServiceEndpoint1 especificado no fragmento de manifesto fornecido após este parágrafo. Além disso, os serviços também podem pedir uma porta específica num recurso. As réplicas de serviço em execução em diferentes nós de cluster podem ser atribuídas a diferentes números de porta, enquanto as réplicas de um serviço em execução no mesmo nó partilham a porta. Em seguida, as réplicas de serviço podem utilizar estas portas conforme necessário para replicação e escutar pedidos de cliente.
Após a ativação de um serviço que especifica um ponto final https, o Service Fabric irá definir a entrada de controlo de acesso para a porta, vincular o certificado de servidor especificado à porta e também conceder a identidade de que o serviço está a ser executado como permissões para a chave privada do certificado. O fluxo de ativação é invocado sempre que o Service Fabric é iniciado ou quando a declaração de certificado da aplicação é alterada através de uma atualização. O certificado de ponto final também será monitorizado para alterações/renovações e as permissões serão periodicamente reaplicadas conforme necessário.
Após a terminação do serviço, o Service Fabric limpará a entrada de controlo de acesso ao ponto final e removerá o enlace de certificado. No entanto, quaisquer permissões aplicadas à chave privada do certificado não serão limpas.
Aviso
Por predefinição, as portas estáticas não devem sobrepor-se ao intervalo de portas da aplicação especificado no ClusterManifest. Se especificar uma porta estática, atribua-a fora do intervalo de portas da aplicação. Caso contrário, resultará em conflitos de portas. Com a versão 6.5CU2, emitiremos um Aviso de Estado de Funcionamento quando detetarmos tal conflito, mas deixaremos que a implementação continue sincronizada com o comportamento enviado 6.5. No entanto, podemos impedir a implementação da aplicação das próximas versões principais.
Com a versão 7.0, emitiremos um Aviso de Estado de Funcionamento quando detetarmos que a utilização do intervalo de portas da aplicação vai além de HostingConfig::ApplicationPortExhaustThresholdPercentage(predefinição 80%).
<Resources>
<Endpoints>
<Endpoint Name="ServiceEndpoint1" Protocol="http"/>
<Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
<Endpoint Name="ServiceEndpoint3" Protocol="https"/>
</Endpoints>
</Resources>
Se existirem vários pacotes de código num único pacote de serviço, o pacote de código também tem de ser referenciado na secção Pontos finais . Por exemplo, se ServiceEndpoint2a e ServiceEndpoint2b forem pontos finais do mesmo pacote de serviço que referencia pacotes de código diferentes, o pacote de código correspondente a cada ponto final será esclarecido da seguinte forma:
<Resources>
<Endpoints>
<Endpoint Name="ServiceEndpoint2a" Protocol="http" Port="802" CodePackageRef="Code1"/>
<Endpoint Name="ServiceEndpoint2b" Protocol="http" Port="801" CodePackageRef="Code2"/>
</Endpoints>
</Resources>
Veja Configurar o Reliable Services com monitorização de estado para ler mais sobre como referenciar pontos finais a partir do ficheiro de definições do pacote de configuração (settings.xml).
Exemplo: especificar um ponto final HTTP para o seu serviço
O seguinte manifesto de serviço define um recurso de ponto final TCP e dois recursos de ponto final HTTP no <elemento Recursos> .
<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="Stateful1Pkg"
Version="1.0.0"
xmlns="http://schemas.microsoft.com/2011/01/fabric"
xmlns:xsd="https://www.w3.org/2001/XMLSchema"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
<ServiceTypes>
<!-- This is the name of your ServiceType.
This name must match the string used in the RegisterServiceType call in Program.cs. -->
<StatefulServiceType ServiceTypeName="Stateful1Type" HasPersistedState="true" />
</ServiceTypes>
<!-- Code package is your service executable. -->
<CodePackage Name="Code" Version="1.0.0">
<EntryPoint>
<ExeHost>
<Program>Stateful1.exe</Program>
</ExeHost>
</EntryPoint>
</CodePackage>
<!-- Config package is the contents of the Config directory under PackageRoot that contains an
independently updateable and versioned set of custom configuration settings for your service. -->
<ConfigPackage Name="Config" Version="1.0.0" />
<Resources>
<Endpoints>
<!-- This endpoint is used by the communication listener to obtain the port number on which to
listen. Note that if your service is partitioned, this port is shared with
replicas of different partitions that are placed in your code. -->
<Endpoint Name="ServiceEndpoint1" Protocol="http"/>
<Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
<Endpoint Name="ServiceEndpoint3" Protocol="https"/>
<Endpoint Name="ServiceEndpoint4" Protocol="https" Port="14023"/>
<!-- This endpoint is used by the replicator for replicating the state of your service.
This endpoint is configured through the ReplicatorSettings config section in the Settings.xml
file under the ConfigPackage. -->
<Endpoint Name="ReplicatorEndpoint" />
</Endpoints>
</Resources>
</ServiceManifest>
Exemplo: especificar um ponto final HTTPS para o seu serviço
O protocolo HTTPS fornece autenticação de servidor e também é utilizado para encriptar a comunicação cliente-servidor. Para ativar o HTTPS no seu serviço do Service Fabric, especifique o protocolo na secção Recursos –> Pontos Finais –> Ponto Final do manifesto de serviço, conforme mostrado anteriormente para o ponto final ServiceEndpoint3.
Nota
Não é possível alterar o protocolo de um serviço durante a atualização da aplicação. Se for alterada durante a atualização, trata-se de uma alteração interruptiva.
Aviso
Ao utilizar HTTPS, não utilize a mesma porta e certificado para diferentes instâncias de serviço (independentes da aplicação) implementadas no mesmo nó. A atualização de dois serviços diferentes com a mesma porta em instâncias de aplicações diferentes resultará numa falha de atualização. Para obter mais informações, veja Atualizar várias aplicações com pontos finais HTTPS .
Eis um exemplo de ApplicationManifest que demonstra a configuração necessária para um ponto final HTTPS. O certificado de servidor/ponto final pode ser declarado por thumbprint ou nome comum do requerente e tem de ser fornecido um valor. O EndpointRef é uma referência a EndpointResource no ServiceManifest e cujo protocolo deve ter sido definido como o protocolo "https". Pode adicionar mais do que um EndpointCertificate.
<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest ApplicationTypeName="Application1Type"
ApplicationTypeVersion="1.0.0"
xmlns="http://schemas.microsoft.com/2011/01/fabric"
xmlns:xsd="https://www.w3.org/2001/XMLSchema"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
<Parameters>
<Parameter Name="Stateful1_MinReplicaSetSize" DefaultValue="3" />
<Parameter Name="Stateful1_PartitionCount" DefaultValue="1" />
<Parameter Name="Stateful1_TargetReplicaSetSize" DefaultValue="3" />
</Parameters>
<!-- Import the ServiceManifest from the ServicePackage. The ServiceManifestName and ServiceManifestVersion
should match the Name and Version attributes of the ServiceManifest element defined in the
ServiceManifest.xml file. -->
<ServiceManifestImport>
<ServiceManifestRef ServiceManifestName="Stateful1Pkg" ServiceManifestVersion="1.0.0" />
<ConfigOverrides />
<Policies>
<EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint3"/>
<EndpointBindingPolicy CertificateRef="SslCertByCN" EndpointRef="ServiceEndpoint4"/>
</Policies>
</ServiceManifestImport>
<DefaultServices>
<!-- The section below creates instances of service types when an instance of this
application type is created. You can also create one or more instances of service type by using the
Service Fabric PowerShell module.
The attribute ServiceTypeName below must match the name defined in the imported ServiceManifest.xml file. -->
<Service Name="Stateful1">
<StatefulService ServiceTypeName="Stateful1Type" TargetReplicaSetSize="[Stateful1_TargetReplicaSetSize]" MinReplicaSetSize="[Stateful1_MinReplicaSetSize]">
<UniformInt64Partition PartitionCount="[Stateful1_PartitionCount]" LowKey="-9223372036854775808" HighKey="9223372036854775807" />
</StatefulService>
</Service>
</DefaultServices>
<Certificates>
<EndpointCertificate Name="SslCertByTP" X509FindValue="FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F0" X509StoreName="MY" />
<EndpointCertificate Name="SslCertByCN" X509FindType="FindBySubjectName" X509FindValue="ServiceFabric-EndpointCertificateBinding-Test" X509StoreName="MY" />
</Certificates>
</ApplicationManifest>
Para clusters do Linux, o meu arquivo é predefinido para a pasta /var/lib/sfcerts.
Para obter um exemplo de uma aplicação completa que utiliza um ponto final HTTPS, veja Add an HTTPS endpoint to an ASP.NET Core Web API front-end service using Kestrel (Adicionar um ponto final HTTPS a um serviço de front-end da API Web ASP.NET Core com o Kestrel).
AcLing de Porta para Pontos Finais HTTP
O Service Fabric irá automaticamente ACL HTTP(S) pontos finais especificados por predefinição. Não executará a ACLing automática se um ponto final não tiver uma SecurityAccessPolicy associada e o Service Fabric estiver configurado para ser executado com uma conta com privilégios de Administrador.
Substituir Pontos Finais no ServiceManifest.xml
Na secção ApplicationManifest, adicione uma secção ResourceOverrides, que será um elemento colateral da secção ConfigOverrides. Nesta secção, pode especificar a substituição da secção Pontos finais na secção de recursos especificada no Manifesto de serviço. Os pontos finais de substituição são suportados no runtime 5.7.217/SDK 2.7.217 e superior.
Para substituir o EndPoint no ServiceManifest com ApplicationParameters, altere o ApplicationManifest como tal:
Na secção ServiceManifestImport, adicione uma nova secção "ResourceOverrides".
<ServiceManifestImport>
<ServiceManifestRef ServiceManifestName="Stateless1Pkg" ServiceManifestVersion="1.0.0" />
<ConfigOverrides />
<ResourceOverrides>
<Endpoints>
<Endpoint Name="ServiceEndpoint" Port="[Port]" Protocol="[Protocol]" Type="[Type]" />
<Endpoint Name="ServiceEndpoint1" Port="[Port1]" Protocol="[Protocol1] "/>
</Endpoints>
</ResourceOverrides>
<Policies>
<EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint"/>
</Policies>
</ServiceManifestImport>
No suplemento Parâmetros abaixo:
<Parameters>
<Parameter Name="Port" DefaultValue="" />
<Parameter Name="Protocol" DefaultValue="" />
<Parameter Name="Type" DefaultValue="" />
<Parameter Name="Port1" DefaultValue="" />
<Parameter Name="Protocol1" DefaultValue="" />
</Parameters>
Ao implementar a aplicação, pode transmitir estes valores como ApplicationParameters. Por exemplo:
PS C:\> New-ServiceFabricApplication -ApplicationName fabric:/myapp -ApplicationTypeName "AppType" -ApplicationTypeVersion "1.0.0" -ApplicationParameter @{Port='1001'; Protocol='https'; Type='Input'; Port1='2001'; Protocol='http'}
Nota: se o valor fornecido para um determinado ApplicationParameter estiver vazio, voltaremos ao valor predefinido fornecido no ServiceManifest para o EndPointName correspondente.
Por exemplo:
Se estiver no ServiceManifest que especificou
<Resources>
<Endpoints>
<Endpoint Name="ServiceEndpoint1" Protocol="tcp"/>
</Endpoints>
</Resources>
Suponha que o valor Port1 e Protocol1 dos Parâmetros da aplicação é nulo ou está vazio. A porta será decidida pelo ServiceFabric e o Protocolo será tcp.
Suponha que especifica um valor errado. Digamos que para a Porta especificou um valor de cadeia "Foo" em vez de um int. New-ServiceFabricApplication comando falhará com um erro: The override parameter with name 'ServiceEndpoint1' attribute 'Port1' in section 'ResourceOverrides' is invalid. The value specified is 'Foo' and required is 'int'.
Passos Seguintes
Este artigo explica como definir pontos finais no manifesto de serviço do Service Fabric. Para obter exemplos mais detalhados, veja:
Para obter instruções sobre como empacotar e implementar uma aplicação existente num cluster do Service Fabric, veja: