Указание ресурсов в манифесте службы

Обзор

Приложения и службы Service Fabric определяются и версионируются с помощью файлов манифеста. Общие сведения о ServiceManifest.xml и ApplicationManifest.xmlсм. в разделе " Манифесты приложений и служб Service Fabric".

Манифест службы позволяет объявлять или изменять ресурсы, используемые службой, без изменения скомпилированного кода. Service Fabric поддерживает настройку ресурсов конечных точек для службы. Доступ к ресурсам, указанным в манифесте службы, можно контролировать с помощью группы безопасности в манифесте приложения. Объявление ресурсов позволяет изменять эти ресурсы во время развертывания, то есть службе не нужно вводить новый механизм конфигурации. Определение схемы для файла ServiceManifest.xml устанавливается с пакетом SDK Service Fabric и инструментами в C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd и документировано в документации схемы ServiceFabricServiceModel.xsd.

Конечные точки

Если ресурс конечной точки определен в манифесте службы, Service Fabric назначает порты из зарезервированного диапазона портов приложения, если порт не указан явным образом. Например, просмотрите конечную точку ServiceEndpoint1 , указанную в фрагменте манифеста, предоставленном после этого абзаца. Кроме того, службы также могут запрашивать определенный порт в ресурсе. Реплики служб, работающие на разных узлах кластера, могут быть назначены различным номерам портов, а реплики службы, работающей на одном узле, совместно используют порт. Затем реплики служб могут использовать эти порты при необходимости для репликации и прослушивания клиентских запросов.

После активации службы, определяющей HTTPS-узел, Service Fabric установит запись контроля доступа для порта, привяжет указанный сертификат сервера к порту, а также предоставит удостоверению, в рамках которой служба выполняется, разрешения на закрытый ключ сертификата. Поток активации вызывается каждый раз, когда Service Fabric начинается, или при изменении декларации сертификата приложения в результате обновления. Сертификат конечной точки также будет отслеживаться на предмет изменений и обновлений, а разрешения будут периодически повторно применяться по мере необходимости.

После окончания службы Service Fabric очистит запись управления доступом к конечной точке и удалит привязку сертификата. Однако все разрешения, примененные к закрытому ключу сертификата, не будут удалены.

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint1" Protocol="http"/>
    <Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
    <Endpoint Name="ServiceEndpoint3" Protocol="https"/>
  </Endpoints>
</Resources>

Если в одном пакете службы есть несколько пакетов кода, в разделе Endpoints также необходимо ссылаться на пакет кода. Например, если ServiceEndpoint2a и ServiceEndpoint2b являются конечными точками из одного пакета службы, ссылающегося на разные пакеты кода, то пакет кода, соответствующий каждой конечной точке, определяется следующим образом:

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint2a" Protocol="http" Port="802" CodePackageRef="Code1"/>
    <Endpoint Name="ServiceEndpoint2b" Protocol="http" Port="801" CodePackageRef="Code2"/>
  </Endpoints>
</Resources>

См. статью Настройка надежных служб с отслеживанием состояния для получения дополнительных сведений о ссылках на конечные точки из файла параметров пакета конфигурации (settings.xml).

Пример: указание конечной точки HTTP для службы

Следующий манифест службы определяет один ресурс конечной точки TCP и два ресурса конечной точки HTTP в элементе <Resources> .

<?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>

Пример: указание конечной точки HTTPS для службы

Протокол HTTPS обеспечивает проверку подлинности сервера и также используется для шифрования связи между клиентом и сервером. Чтобы включить HTTPS в службе Service Fabric, укажите протокол в разделе "Ресурсы —> конечные точки"> манифеста службы, как показано ранее для конечной точки ServiceEndpoint3.

Ниже приведен пример ApplicationManifest, демонстрирующий конфигурацию, необходимую для конечной точки HTTPS. Сертификат сервера или конечной точки может быть указан отпечатком или общим именем субъекта, и необходимо указать значение. EndpointRef — это ссылка на EndpointResource в ServiceManifest, для которого должен быть установлен протокол 'https'. Можно добавить несколько 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>

Для кластеров Linux хранилище MY по умолчанию использует папку /var/lib/sfcerts.

Пример полного приложения, использующего конечную точку HTTPS, см. в статье о добавлении конечной точки HTTPS в интерфейсную службу ASP.NET Core Web API с помощью Kestrel.

Настройка ACL для HTTP конечных точек

Service Fabric автоматически назначит список управления доступом (ACL) для конечных точек HTTP(S), указанных по умолчанию. Он не будет выполнять автоматическое управление доступом, если конечная точка не связана с SecurityAccessPolicy, и если Service Fabric настроена для работы с использованием учетной записи с правами администратора.

Переопределение конечных точек в ServiceManifest.xml

В ApplicationManifest добавьте раздел ResourceOverrides, который будет одноуровневой частью раздела ConfigOverrides. В этом разделе можно указать переопределение для раздела "Конечные точки" в разделе ресурсов, указанном в манифесте службы. Переопределение конечных точек поддерживается в среде выполнения 5.7.217/SDK 2.7.217 и более поздних версий.

Чтобы переопределить конечную точку в манифесте службы с помощью параметров приложения, измените манифест приложения следующим образом:

В разделе ServiceManifestImport добавьте новый раздел 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>

В разделе "Параметры" добавьте следующее:

  <Parameters>
    <Parameter Name="Port" DefaultValue="" />
    <Parameter Name="Protocol" DefaultValue="" />
    <Parameter Name="Type" DefaultValue="" />
    <Parameter Name="Port1" DefaultValue="" />
    <Parameter Name="Protocol1" DefaultValue="" />
  </Parameters>

При развертывании приложения эти значения можно передать в качестве ApplicationParameters. Рассмотрим пример.

PS C:\> New-ServiceFabricApplication -ApplicationName fabric:/myapp -ApplicationTypeName "AppType" -ApplicationTypeVersion "1.0.0" -ApplicationParameter @{Port='1001'; Protocol='https'; Type='Input'; Port1='2001'; Protocol='http'}

Примечание. Если значение, предоставленное для заданного ApplicationParameter, пусто, мы возвращаемся к значению по умолчанию, предоставленному в ServiceManifest для соответствующего EndPointName.

Рассмотрим пример.

Если в указанном параметре ServiceManifest

  <Resources>
    <Endpoints>
      <Endpoint Name="ServiceEndpoint1" Protocol="tcp"/>
    </Endpoints>
  </Resources>

Предположим, что значение Port1 и Protocol1 для параметров приложения равно null или пусто. Порт будет определен ServiceFabric, а протокол будет tcp.

Предположим, что вы указали неправильное значение. Предположим, вы указали для порта строковое значение "Foo" вместо целого числа. Команда New-ServiceFabricApplication завершится ошибкой: The override parameter with name 'ServiceEndpoint1' attribute 'Port1' in section 'ResourceOverrides' is invalid. The value specified is 'Foo' and required is 'int'.

Дальнейшие шаги

В этой статье объясняется, как определить конечные точки в манифесте службы Service Fabric. Более подробные примеры см. в следующей статье.

Пошаговое руководство по упаковке и развертыванию существующего приложения в кластере Service Fabric см. в статье: