Edge for Private Cloud 4.54.00'daki değişiklikler

Değişikliklere genel bakış

Edge for Private Cloud 4.54.00, platformun güvenlik durumunu iyileştiren birden fazla değişiklik sunar ve platform bileşenlerini Java 21 ile çalışacak şekilde günceller. Aşağıdaki bölümlerden ikisi bu değişiklikleri kapsar:

• Java Callout politikası değişiklikleri
• TLS ve şifre paketi değişiklikleri

Bu değişikliklere ek olarak, özel Değişiklik algılama aracı kılavuzunu inceleyin. Bu yardımcı program, bu yükseltme sonucunda kesintiye neden olabilecek proxy'lerde, paylaşılan akışlarda veya kümenizdeki diğer yapıtlarda yapılan değişiklikleri belirlemek için kullanıma sunulmuştur.

4.53.01 sürümünde bulunan üç özellik, Edge for Private Cloud 4.54.00'da desteklenmez. Yükseltmenizi planlamadan önce 4.54.00 sürümünde desteklenmeyen özellikler bölümünü inceleyin.

4.54.00 sürümünde desteklenmeyen özellikler

Edge for Private Cloud 4.54.00, 4.53.01 sürümünde bulunan aşağıdaki özellikleri desteklemez. Dağıtımınızda bunlardan herhangi biri kullanılıyorsa 4.54.00 sürümüne yükseltmeyin. 4.53.01 sürümünde kalın ve Apigee Destek Ekibi ile iletişime geçin.

• Google Distributed Cloud (GDC) hava boşluklu ortamda kurulum. Edge for Private Cloud 4.54.00, hava boşluklu GDC ortamları için onaylanmamıştır. 4.53.01 sürümü prosedürü için Google Distributed Cloud hava boşluklu ortamda Apigee'yi yükleme başlıklı makaleyi inceleyin.
• FIPS özellikli RHEL 8.X veya Rocky 8.X. Edge for Private Cloud 4.54.00, FIPS özellikli bir RHEL 8.X veya Rocky 8.X ana makinesine yüklemeyi desteklemez. FIPS modu etkinleştirilmediğinde bu işletim sistemleri desteklenir. 4.54.00 sürümünün yapılandırma konularında, 4.53.01 sürümünün sağladığı FIPS'e özel kılavuzlar da yer almaz. Bu kılavuzlar arasında BCFKS anahtar deposu hazırlığı, FIPS_OS sessiz yapılandırma özelliği ve PKCS12 anahtar deposu yapılandırması bulunur. 4.53.01 sürümüyle ilgili kılavuz için FIPS özellikli RHEL 8.X veya Rocky 8.X'te Edge for Private Cloud başlıklı makaleyi inceleyin.
• Güney yönlü Donanım Güvenlik Modülü (HSM) entegrasyonu. Edge for Private Cloud 4.54.00, Mesaj İşleyicilerden Entrust nShield ağ HSM'si kullanan arka uç hedef hizmetlerine giden TLS bağlantılarını desteklemez. 4.53.01 sürümü prosedürü için Southbound Hardware Security Module Integration Guide for Apigee Edge for Private Cloud (Özel Bulut için Apigee Edge'e Yönelik Güney Donanım Güvenlik Modülü Entegrasyon Kılavuzu) başlıklı makaleyi inceleyin.

Java Callout politikası değişiklikleri

Edge for Private Cloud 4.54.00'te, Mesaj İşleyici, Yönetim Sunucusu ve Yönlendirici gibi temel platform bileşenleri Java 21 LTS'de çalışacak şekilde güncellendi. Java 21, Java platformunu modernize eder. Bu kapsamda eski Java EE ve CORBA modülleri (JEP 320) ile eski dahili yardımcı sınıflar kaldırılır ve güçlü modüler kapsülleme (JEP 403) uygulanır.

Bu değişiklikler nedeniyle, özel JavaCallout politikaları veya özel kaynak JAR'ları (proxy, ortam veya kuruluş düzeyinde depolanan) içeren API proxy'leri 4.54.00 sürümüne yükseltildiğinde kesinti yaşayabilir.

Java açıklama balonlarını etkileyebilecek değişiklik kategorileri

1. Java EE ve CORBA modülleri kalıcı olarak kaldırıldı (JEP 320): Daha önce Java 8 çalışma zamanında yerleşik olarak bulunan modüller (JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.* ve CORBA org.omg.* dahil) Java SE'den kaldırıldı. Bağımsız alternatifleri paketlemeden bu paketlere referans veren belirtme çizgileri, çalışma zamanında NoClassDefFoundError ile başarısız olur.
2. Dahili yardımcı sınıflar kaldırıldı: sun.misc.BASE64Encoder ve sun.misc.BASE64Decoder gibi eski dahili yardımcılar kaldırıldı. Bu sınıfları çağıran açıklama metinleri NoClassDefFoundError ile başarısız olur.
3. Java dahili bileşenlerinin güçlü kapsüllemesi (JEP 403): java.base içindeki dahili paketlere (ör. sun.security.*, sun.reflect.* ve com.sun.*) özel açıklama metinlerinden yansıtmalı olarak erişilemez. Yansıtıcı çağrılar, çalışma zamanında InaccessibleObjectException ile başarısız olur.
4. Mevcut Java sınıflarında yöntem imzası değişiklikleri ve kaldırma işlemleri: Belirli Java modüllerinde sınıf, Java 21'de mevcut kalır ancak belirli kurucular veya yöntem imzaları kaldırılmış, desteği sonlandırılmış ya da değiştirilmiştir (ör. org.w3c.dom.Document ve ilgili XML ayrıştırma sınıflarındaki belirli DOM ayrıştırma yöntemleri).

   Araç algılama: Değişiklik algılama aracı, METHOD_SIGNATURE_MODIFICATION kategorisi altındaki bu sınıflara yapılan referansları MEDIUM Etki Kesinliği ile işaretler ve geliştiricileri, değiştirilen yöntem çağrıları için açıklama metinlerinin kaynak kodunu incelemeye yönlendirir.

Düzeltme stratejileri

Yükseltme yapmadan önce Java Callout politikalarınızın ve özel JAR kaynaklarınızın Java 21 çalışma zamanı ile uyumlu olduğundan emin olun. Değişiklik algılama aracını kullanarak kümenizdeki etkilenen API proxy'lerini, paylaşılan akışları ve ortam veya kuruluş JAR kaynaklarını belirleyebilirsiniz.

Bu bölümde açıklanan düzeltme stratejileri genel kılavuzlardır ve birbirini dışlamaz. Operasyonel gereksinimlerinize bağlı olarak stratejileri birleştirebilirsiniz. Örneğin, Mesaj İşleyici yükseltmeleri sırasında sıfır kesinti süresi elde etmek için 2. stratejiyi kullanarak açıklama metni kaynak kodunu modernize edebilir ve güncellenmiş proxy düzeltmelerini 3B stratejisini kullanarak dağıtabilirsiniz.

3A, 3B ve 3C stratejileri, aynı operasyonel yaklaşımı uygulamanın üç farklı yoludur: proxy paketini değiştirmeden düğümü yükseltmek ve proxy'yi farklı zamanlarda yeniden dağıtmak. API kullanılabilirliği gereksinimlerinize göre bunlardan birini veya birkaçını seçin.

Dağıtımınız için en uygun yaklaşımı seçmek üzere aşağıdaki karar kılavuzunu inceleyin:

Java Callout azaltma işlemleri için karar kılavuzu:

1. strateji: Paket halinde sunulan JAR'lar aracılığıyla çift uyumlu proxy (Sıfır kesinti süresi için yükseltmeden önce test edin)

Ne zaman kullanılır? Bu stratejiyi şu durumlarda kullanın:

• Çift uyumlu bağımsız bir yedek kitaplık mevcuttur: Gerekli işlevi uygulayan ve kaynak kodu değişikliği gerektirmeden doğrudan API proxy'nize paketlenebilen bir yedek JAR mevcuttur.
• Mevcut API proxy'lerinizin ve Java belirtme öğelerinizin hem mevcut sürümünüzde (ör. Edge for Private Cloud 4.53.01) hem de yeni sürümde (Edge for Private Cloud 4.54.00) sorunsuz çalışmasını istiyorsunuz.
• Edge for Private Cloud kümenizi yükseltmeden önce hazırlık ve üretim ortamlarınızdaki tüm değişiklikleri test edip doğrulamak, canlı trafikte beklenmedik sorunlar ve kesinti yaşanmamasını sağlamak istiyorsunuz.
• Java Callout iş mantığınızı yeniden yazmaktan veya yeniden düzenlemekten kaçınmak istiyorsanız.

İşleyiş şekli: Java 8'de belirli kitaplıklar (ör. JAXB javax.xml.bind.* veya Activation javax.activation.*) doğrudan Java 8 çalışma zamanına yerleştirilmiştir. Bu nedenle, geliştiricilerin proxy paketlerine ek JAR dosyaları eklemesi gerekmiyordu. Java 21'de bu kitaplıklar Java çalışma zamanından kaldırıldı.

Proxy'nizi Edge for Private Cloud 4.53.x ve 4.54.00'da "çift uyumlu" hale getirmek için:

1. Belirtme öğeniz için gereken eksik kitaplığı (örneğin, JAXB veya Etkinleştirme) belirleyin.
2. Bağımsız açık kaynaklı yedek JAR'ı (ör. jakarta.xml.bind-api-2.3.3.jar ve jaxb-runtime-2.3.8.jar) edinin.
3. Yedek JAR'ı doğrudan apiproxy/resources/java/ altındaki proxy paketine yerleştirin veya proxy düzeyinde Resource Files API'yi kullanarak proxy düzeltmesine yükleyin ya da ortam düzeyinde veya kuruluş düzeyinde kaynak dosyası olarak yükleyin. Kaynak dosyalarını yönetme hakkında daha fazla bilgi için Apigee kaynak dosyaları belgelerine bakın.
4. Yükseltme işleminden önce dağıtın ve test edin: Edge for Private Cloud 4.53.x ve 4.54.00'deki Mesaj İşleyiciler, sınıfları bu paketlenmiş JAR'lardan yükler. Bu güncellenmiş proxy paketini dağıtabilir ve mevcut Edge for Private Cloud 4.53.x kümenizdeki yapay trafikle test edebilirsiniz.
5. Mesaj İşlemciler'de harici izin verilen paket yüklemeyi etkinleştirme (4.54.00 için zorunlu): Private Cloud için Edge 4.54.00'te varsayılan olarak, kaldırılan Java paketlerinin (ör. javax.xml.bind.* ve javax.activation.*) harici veya paket hâlindeki kaynak JAR'lardan yüklenmesi devre dışıdır (conf_system_java.21.enable.external.allowed.packages=false). Bu nedenle, JAR'ları tek başına paketlemek varsayılan olarak çalışmaz. /opt/apigee/customer/application/message-processor.properties içinde kodla yapılandırma (CwC) kullanarak bu özelliği etkinleştirmeniz gerekir (Bu özelliği, Mesaj İşleyici düğümünü yükseltmeden önce yapılandırabilir veya yükselttikten sonra ayarlayıp Mesaj İşleyici'yi yeniden başlatabilirsiniz):

   conf_system_java.21.enable.external.allowed.packages=true

6. Yükseltme sonrasında canlı trafik sorunu yaşanmaz: Kümeniz daha sonra conf_system_java.21.enable.external.allowed.packages=true etkinleştirilmiş şekilde Edge for Private Cloud 4.54.00'e yükseltildiğinde, Mesaj İşleyici gerekli JAR'a zaten sahiptir ve sınıfları paketlenmiş kaynak dosyasından herhangi bir hata olmadan (NoClassDefFoundError) yükler. Bu sayede sorunsuz ve kesintisiz bir yükseltme sağlanır.

Kod örneği: Sipariş XML doğrulaması ve ayrıştırma açıklama metni

JAXB (JAXBContext ve Unmarshaller) kullanarak gelen XML siparişlerini ayıklayan ve doğrulayan tipik bir Apigee Java Callout'u ele alalım.

• Düzeltmeden önce (Edge for Private Cloud 4.54.00'da başarısız olur): Edge for Private Cloud 4.53.x'te proxy paketi yalnızca açıklama balonu JAR'ını içerir ve JAXB için yerleşik Java 8 çalışma zamanı kitaplıklarını kullanır:

  apiproxy/
    resources/
      java/
        OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

  Java açıklama metni uygulaması:

  package com.example.callout;
  
  // other required imports
  import java.io.StringReader;
  import javax.xml.bind.JAXBContext;
  import javax.xml.bind.Unmarshaller;
  
  public class OrderXmlParserCallout implements Execution {
      @Override
      public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
          try {
              String requestXml = messageContext.getMessage().getContent();
              JAXBContext jaxbContext = JAXBContext.newInstance(Order.class);
              Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
              Order order = (Order) unmarshaller.unmarshal(new StringReader(requestXml));
              messageContext.setVariable("order_id", order.getId());
              return ExecutionResult.SUCCESS;
          } catch (Exception e) { }
      }
  }

  Hata: Edge for Private Cloud 4.53.x'te bu işlem sorunsuz bir şekilde yürütülür. Düğüm, Edge for Private Cloud 4.54.00'e yükseltildikten sonra bu proxy, istek işleme sırasında hemen başarısız olur:

  java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
          at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)

• Düzeltmeden sonra (Private Cloud 4.53.x ve 4.54.00 için Edge'de çift uyumlu): Java Callout kodunuzu yeniden yazmanız veya yeniden derlemeniz gerekmez. Bağımsız JAR'ları sağlayarak proxy'nizi doğrudan çift uyumlu hale getirebilirsiniz:
  1. Bağımsız JAR'ları doğrudan paketleyin veya yükleyin: Bağımsız JAXB kitaplıklarını (jakarta.xml.bind-api-2.3.3.jar ve jaxb-runtime-2.3.8.jar) alın ve proxy paketinizin içine apiproxy/resources/java/ altına yerleştirin:

     apiproxy/
       resources/
         java/
           OrderXmlParserCallout.jar
           jakarta.xml.bind-api-2.3.3.jar
           jaxb-runtime-2.3.8.jar

     Alternatif olarak, proxy düzeyinde Resource Files API'yi kullanarak veya ortam düzeyinde ya da kuruluş düzeyinde jakarta.xml.bind-api-2.3.3.jar ve jaxb-runtime-2.3.8.jar öğelerini kaynak dosyaları olarak yükleyin. Böylece aynı kapsamdaki tüm proxy'ler, bunları her bir proxy paketine eklemeden paylaşabilir.

     Proxy paketinizi Maven kullanarak kaynaktan oluşturuyorsanız bu bağımlılıkları pom.xml dosyanızda tanımlayın. Böylece, derleme sırasında otomatik olarak paketlenirler.

  2. Mevcut 4.53.x kümenizde dağıtma ve test etme: Güncellenmiş proxy paketini mevcut Edge for Private Cloud 4.53.x ortamınıza dağıtın ve test aramaları gönderin. Private Cloud için Edge 4.53.x Mesaj İşleyiciler, sınıfları bu paketlenmiş JAR'lardan yüklediğinden, açıklama metninin aynı şekilde çalışmaya devam ettiğini doğrulayabilirsiniz.
  3. CwC aracılığıyla harici izin verilen paket yüklemeyi etkinleştirme: Harici izin verilen paketlerin yüklenmesi Edge for Private Cloud 4.54.00'da (conf_system_java.21.enable.external.allowed.packages=false) varsayılan olarak devre dışı bırakıldığından /opt/apigee/customer/application/message-processor.properties içindeki her Mesaj İşleyici düğümünde yapılandırmalı kod (CwC) kullanarak etkinleştirin:

     conf_system_java.21.enable.external.allowed.packages=true

  4. Yükseltme sonrasında canlı trafik sorunu yaşanmaz: 4.53.x ortamınızda doğrulandıktan ve CwC özelliğiyle yapılandırıldıktan sonra proxy'niz tamamen hazır olur. Kümenizi Edge for Private Cloud 4.54.00'e yükselttiğinizde Mesaj İşleyici, paketlenmiş JAXB sınıflarını yükleyerek sıfır hata ve sıfır canlı trafik kesintisi sağlar.

2. strateji: Alternatif uygulama (Kod ve bağımlılık modernizasyonu)

Ne zaman kullanılır? Proxy kaynak kodunun kolayca yönetildiği etkin kod tabanları için önerilir. Bu, Java 21 uyumluluğu için en temiz uzun vadeli yaklaşımdır. Kullanıma sunma notu: Modernize edilmiş proxy düzeltmelerinin dağıtılması için Mesaj İşleyici koordinasyonu gerektiğinden bu stratejiyi Strateji 3A (planlı bir bakım dönemi sırasında) veya Strateji 3B (paralel Mesaj İşleyiciler ile sıfır kesinti süresi elde etmek için) ile eşleştirin.

İşleyiş şekli: Kaldırılan Java dahili sınıflarını resmi standart Java SE API'leri veya açık kaynaklı bağımsız eşdeğerleriyle değiştirin ve gerekli üçüncü taraf bağımlılıklarını doğrudan proxy paketi kaynak dosyalarınızda veya POM'da paketleyin.

Kod örnekleri:

1. örnek: Yöntem ve kod modernizasyonu (Kaldırılan dahili yardımcı programları değiştirme)

Java 8'de, açıklama metinleri genellikle sun.misc.BASE64Encoder gibi dahili yardımcı sınıfları kullanıyordu. Modern Java'da bu sınıflar kaldırıldı ancak standart java.util.Base64 API, harici bağımlılık JAR'ları gerektirmeden doğrudan değişim sağlar:

• Önce (Eski Java 8 uygulaması):

  // Incompatible in Edge for Private Cloud 4.54.00: sun.misc package removed
  import sun.misc.BASE64Encoder;
  // other required imports
  
  public class Base64EncodeCallout implements Execution {
      @Override
      public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
          BASE64Encoder encoder = new BASE64Encoder();
          String encoded = encoder.encode("ApigeePayload".getBytes());
          messageContext.setVariable("encoded_data", encoded);
          return ExecutionResult.SUCCESS;
      }
  }

• Sonra (Java 21 uyumlu uygulama):

  // Fully compatible with Java 21: uses standard Java SE java.util.Base64 (no external JARs needed)
  import java.util.Base64;
  // other required imports
  
  public class Base64EncodeCallout implements Execution {
      @Override
      public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
          String encoded = Base64.getEncoder().encodeToString("ApigeePayload".getBytes());
          messageContext.setVariable("encoded_data", encoded);
          return ExecutionResult.SUCCESS;
      }
  }

2. örnek: Paketlenmiş kitaplıkla içe aktarma düzeyinde yeniden düzenleme (JAXB Ad Alanı Önek Eşleyici)

Java 8'de, XML ad alanı öneklerini özelleştiren API proxy'leri genellikle Sun'ın dahili JAXB eşleyicisi com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper'ni genişletiyordu. Java 21'de dahili Sun paketleri kaldırılmıştır ve bunlara erişilemez.

Bağımsız açık kaynak kitaplığı (org.glassfish.jaxb:jaxb-runtime), com.sun.xml.bind.marshaller.NamespacePrefixMapper altında aynı sınıfı sağlar. Tüm yöntem imzaları, parametreler ve dönüş türleri aynıdır. Kod değişikliği yalnızca içe aktarma ifadesindedir:

• Önce (Eski Java 8 uygulaması):

  // In Java 8: Relied on internal Sun class in Java 8 runtime
  import com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper;
  public class CustomNamespaceMapper extends NamespacePrefixMapper {
      @Override
      public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
          if ("http://schemas.example.com/orders".equals(namespaceUri)) {
              return "ord";
          }
          return suggestion;
      }
  }

• Sonra (Java 21 uyumlu uygulama):

  // In Java 21: Identical methods and logic; ONLY the import statement changes (".internal." removed)
  import com.sun.xml.bind.marshaller.NamespacePrefixMapper;
  public class CustomNamespaceMapper extends NamespacePrefixMapper {
      @Override
      public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
          if ("http://schemas.example.com/orders".equals(namespaceUri)) {
              return "ord";
          }
          return suggestion;
      }
  }

• Paketlenmiş bağımlılık yapılandırması (pom.xml): Bu sınıfı çalışma zamanında sağlamak için bağımsız JAXB kitaplıklarını apiproxy/resources/java/ içinde paketleyin veya pom.xml dosyanızda tanımlayın:

  <dependencies>
      <!-- Standalone JAXB API for Java 21 -->
      <dependency>
          <groupId>jakarta.xml.bind</groupId>
          <artifactId>jakarta.xml.bind-api</artifactId>
          <version>2.3.3</version>
      </dependency>
      <!-- Standalone JAXB Runtime providing com.sun.xml.bind.marshaller.NamespacePrefixMapper -->
      <dependency>
          <groupId>org.glassfish.jaxb</groupId>
          <artifactId>jaxb-runtime</artifactId>
          <version>2.3.8</version>
      </dependency>
  </dependencies>

3A stratejisi: Planlı bakım nedeniyle kapalı kalma süresi (Yerinde yeniden dağıtım)

Kullanım zamanı: Kısa süreli hizmet kesintisinin kabul edilebilir olduğu, planlanmış operasyonel bakım dönemleri olan ortamlar için önerilir.

Prosedür:

1. API tüketicileriyle planlı bir bakım dönemi koordine etme
2. Yükseltme yolları kılavuzunu uygulayarak Edge for Private Cloud bileşenlerinizi 4.54.00 sürümüne yükseltin.
3. Yeni Edge kullanıcı arayüzünü veya Apigee Management API'yi (Dağıtımlar) kullanarak API proxy'nizin önceden derlenmiş, 4.54.00 ile uyumlu düzeltmesini dağıtın.
4. Mesaj İşleyicilere yapay test istekleri göndererek ve İzleme aracını kullanarak günlükleri inceleyerek açıklama metni yürütme işlemini doğrulayın.
5. Bakım dönemini kapatın ve genel trafiği yeniden açın.

Strateji 3B: Yeni ortam oluşturma (Sıfır kesinti süreli taşıma)

Kullanım zamanı: Sıfır kesinti süresi gerektiren, görev açısından kritik üretim ortamları için önerilir. Java açıklamanız Java 8 ve Java 21'de aynı anda çalışacak şekilde güncellenemiyorsa bu seçeneği kullanın.

İşleyiş şekli: Bu strateji, farklı sürümlerdeki Mesaj İşleyici düğümlerini bağlayabilmeniz için bir veya daha fazla yeni ortamın tedarik edilmesini içerir. Ardından, Java 8 ile uyumlu proxy'leri 4.53.X Mesaj İşleyiciler ile bağlı ortama, Java 21 ile uyumlu proxy'leri ise 4.54.00 Mesaj İşleyiciler ile bağlı ortama dağıtın. Ardından, trafiği yalnızca Java 21 uyumlu proxy'ye yönlendirmek için bir yük dengeleyici veya başka yönlendirme teknikleri kullanın.

Bu stratejide, sıfır kesinti süreli bir geçiş için kuruluşların, ortamların ve mesaj işlemcilerin nasıl etkileşim kurduğunu anlamak çok önemlidir (daha fazla bilgi için Apigee Edge kuruluş yapısı başlıklı makaleyi inceleyin):

• Apigee kuruluşu, birden fazla ortam (ör. prod, test) içeren üst düzey bir yönetim sınırıdır.
• API proxy düzeltmesi belirli bir ortama dağıtılır. Yalnızca bu ortama açıkça bağlı olan Mesaj İşlemciler, proxy düzeltmesini yükler ve yürütür.

+------------------------------------------------------------------------+
|                          Apigee Organization                           |
|                                                                        |
|  Existing Environment (prod)            Temporary Env (prod-migration) |
|  +--------------------------------+     +----------------------------+ |
|  | Current 4.53.01 MP Nodes       |     | New 4.54.00 MP Nodes       | |
|  |               |                |     |              |             | |
|  | Proxy Rev N (4.53.01)          |     | Proxy Rev N+1 (Modernized) | |
|  +--------------------------------+     +----------------------------+ |
+------------------------------------------------------------------------+
                   ^                                    ^
                   | Step 1: Normal Live                | Step 2: Canary
                   |         Traffic (prod)             | Step 3: Complete
          +------------------------------------------------------+
          |       Upstream Load Balancer / Ingress Router        |
          +------------------------------------------------------+

Prosedür:

1. Geçici bir ortam oluşturun: Kuruluşunuzda özel bir sanal ana makine ve bağlantı noktası içeren yeni bir ortam (ör. prod-migration) oluşturun (Sanal ana makineleri ve ortamları ayarlama bölümündeki adımları uygulayın).
2. 4.54.00 Mesaj İşleyici düğümlerini temel hazırlayın: Yeni veya geçici sanal makine örneklerine Edge for Private Cloud 4.54.00'ü yükleyin ve bu düğümleri prod-migration'ye bağlayın (Mesaj İşleyici ekleme bölümüne bakın).
3. Etkilenen proxy'leri belirleme ve güncellenmiş düzeltmeler oluşturma: Java Callout'ları kullanan API proxy'lerini belirleyin (değişiklik algılama aracını kullanarak) ve etkilenen her proxy'nin Edge for Private Cloud 4.54.00 uyumlu Java Callout'ları içeren yeni bir düzeltmesini oluşturun (Strateji 1 veya Strateji 2'yi uygulayarak).
4. Modernize edilmiş proxy düzeltmelerini geçici ortama dağıtın: Güncellenmiş, uyumlu proxy düzeltmelerini yalnızca prod-migration ortamına dağıtın.
5. Trafiği doğrulama ve kaydırma: Yeni sanal ana makineye karşı sentetik doğrulama testleri yürütün. Doğrulama tamamlandıktan sonra harici yük dengeleyicinizi (F5, NGINX), istemci trafiğini prod adresinden prod-migration adresine yönlendirecek şekilde yapılandırın.
6. Orijinal düğümleri yükseltme ve geri geçiş yapma: Eski proxy'lerin prod üzerindeki dağıtımını kaldırın. Yükseltme yolları kılavuzunu uygulayarak orijinal Mesaj İşleyici düğümlerini 4.54.00 sürümüne yükseltin. Modernize edilmiş proxy düzeltmelerini prod ortamına dağıtın, yük dengeleyici trafiğini tekrar prod ortamına yönlendirin ve işlemi doğrulayın.
7. Geçici ortamı kullanımdan kaldırın: Proxy'leri prod-migration ortamından kaldırın, geçici Mesaj İşleyici düğümlerini kaldırın ve geçici ortamı silin.

Strateji 3C: Düğüm düzeyinde harici kitaplık yerleşimi (paylaşılan yedek kitaplıklar)

Kullanım zamanı: Java 21'de kaldırılan Java sınıflarını kullanan birden fazla API proxy'niz varsa ve yükseltme işleminden önce her bir proxy paketini yeniden derlemek veya yeniden paketlemek operasyonel açıdan mümkün değilse önerilir.

İşleyiş şekli: Edge for Private Cloud 4.54.00'te, Mesaj İşleyiciler eksik Java sınıflarını özel bir düğüm dizininden yüklemek için bir mekanizma sağlar: $APIGEE_ROOT/data/edge-message-processor/external-lib.

Bu mekanizma etkinleştirildiğinde, Mesaj İşleyici varsayılan çözünürlüğe geri dönmeden önce eksik sınıflar için bu dizini kontrol eder. Eksik sınıfları üçüncü taraf kitaplık JAR'larından alarak veya gerekli sınıfları bir JAR'da toplayıp external-lib dizinine yerleştirerek sağlayabilirsiniz.

Prosedür:

1. Her Mesaj İşleyici düğümünde harici kitaplık dizini oluşturun:

   mkdir -p /opt/apigee/data/edge-message-processor/external-lib

2. Gerekli JAR'ları dizine yerleştirin: Gerekli sınıfları içeren JAR dosyalarını /opt/apigee/data/edge-message-processor/external-lib dizinine kopyalayın.
3. Uygun dosya izinlerini ayarlayın: apigee hizmet kullanıcısının okuma izinlerine sahip olduğundan emin olun:

   chown -R apigee:apigee /opt/apigee/data/edge-message-processor/external-lib
   chmod 755 /opt/apigee/data/edge-message-processor/external-lib
   chmod 644 /opt/apigee/data/edge-message-processor/external-lib/*.jar

4. Mesaj İşleyici yapılandırmasında harici paket yüklemeyi etkinleştirme: Edge for Private Cloud 4.54.00'te varsayılan olarak, harici izin verilen paketlerin yüklenmesi devre dışıdır (conf_system_java.21.enable.external.allowed.packages=false). Mesaj İşleyici'nin /opt/apigee/data/edge-message-processor/external-lib'teki sınıfları çözmesini ve yüklemesini sağlamak için yapılandırmalı kod (CwC) kullanarak /opt/apigee/customer/application/message-processor.properties'te bu özelliği etkinleştirmeniz gerekir:

   conf_system_java.21.enable.external.allowed.packages=true

5. Mesaj İşleyici'yi yeniden başlatın:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

4. strateji: JVM işaretleri (--add-opens / --add-exports — dikkatli olun ve son çare olarak kullanın)

Ne zaman kullanılmalı: Bu stratejiyi, kaynak kodun kullanılamadığı, tedarikçilerin Java 21 güncellemelerini yayınlamadığı ve JAR'ın kesinlikle dahili Java paketlerine yansıtıcı erişime bağlı olduğu kapalı kaynak üçüncü taraf satıcı kitaplıkları için son çare olarak kullanın.

Prosedür:

1. Yansıma için kullanılan erişilemeyen paketi belirleyin: Üçüncü taraf kitaplığınız tarafından yansıma yoluyla erişilen dahili Java modülünü ve paketini belirleyin. Not: Bu yansıma hataları, Edge for Private Cloud 4.54.00'da yalnızca Java 21'de ortaya çıkar ve 4.53.x sürümünün günlüklerinde görünmez. Yükseltme işleminden sonra, gerekli modülü ve paketi tanımlayan InaccessibleObjectException için Mesaj İşleyici günlüklerini (/opt/apigee/var/log/edge-message-processor/system.log) kontrol edin:

   java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module

2. Yapılandırmalı kod (CwC) kullanarak /opt/apigee/customer/application/message-processor.properties dosyasını düzenleyin (dosya yoksa oluşturun).
3. Hedeflenen --add-opens veya --add-exports işaretlerini bin_setenv_ext_jvm_opts öğesine ekleyin.

   # Configure targeted JVM module access for closed-source legacy callouts (enclosed in double quotes)
   bin_setenv_ext_jvm_opts="-XX:+UseG1GC -XX:+AlwaysPreTouch --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.misc=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED --add-opens java.base/sun.security.x509=ALL-UNNAMED"

4. Dosya sahipliğinin ve izinlerinin doğru olduğundan emin olun:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
   chmod 644 /opt/apigee/customer/application/message-processor.properties

5. apigee-service kullanarak Mesaj İşleyici'yi yeniden başlatın:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

TLS ve şifre paketi değişiklikleri

Edge for Private Cloud 4.54.00'te, Mesaj İşleyici, Yönetim Sunucusu ve Yönlendirici gibi temel platform bileşenleri Java 21 LTS'de çalışacak şekilde güncellendi. Bu güncelleme, TLS 1.3'ü varsayılan olarak etkinleştirerek (JEP 332) kriptografik güvenliği modernize eder. Mesaj İşleyiciler artık giden arka uç bağlantıları için tercih edilen protokol olarak TLS 1.3'ü kullanır. Arka uç TLS 1.3'ü desteklemiyorsa TLS 1.2'ye geri döner.

Eski arka uç gereksinimleri ve düzeltme

Java 21 kriptografik temeli, jdk.tls.disabledAlgorithms içinde varsayılan olarak devre dışı bırakılan protokollerin ve şifreleme paketlerinin listesini günceller (ör. eski TLS protokolleri ve ileriye dönük gizlilik sağlamayan statik RSA anahtar değişim paketleri: TLS_RSA_*). Kendi Java 21 çalışma zamanınızı sağladığınız için devre dışı bırakılan protokollerin ve şifreleme paketlerinin tam listesi, özel Java 21 uygulamanıza bağlıdır.

Mevcut API proxy'leriniz, devre dışı bırakılmış protokoller veya statik RSA şifreleri gerektiren eski arka uç altyapısına bağlanıyorsa aşağıdaki işlemleri inceleyin:

• Arka uç güvenliğini modernize etme (Önerilen): Hedef sunucuları ve yük dengeleyicileri, modern ECDHE şifre paketleriyle TLS 1.2 veya TLS 1.3'ü destekleyecek şekilde yükseltin. API proxy'lerinizde protokolleri ve şifre paketlerini yapılandırmak için Edge'den arka uca TLS'yi yapılandırma ve TLS/SSL TargetEndpoint yapılandırma referansı (veya TargetServers kullanıyorsanız Arka uç sunucuları arasında yük dengeleme) başlıklı makaleleri inceleyin.
• CwC kullanarak eski algoritmaları yeniden etkinleştirme (yükseltme sırasında geçici önlem): Arka uç yükseltmeleri platform yükseltmesinden önce tamamlanamazsa yapılandırmalı kod (CwC) kullanarak gerekli algoritmaları geçici olarak yeniden etkinleştirebilirsiniz:
  1. Java 21 kurulumunuzdaki varsayılan jdk.tls.disabledAlgorithms değerini (ör. $JAVA_HOME/conf/security/java.security içinde) kontrol edin.
  2. /opt/apigee/customer/application/message-processor.properties içindeki conf_jvmsecurity_jdk.tls.disabledAlgorithms politikasını aynı devre dışı bırakılmış algoritmalar listesiyle geçersiz kılın ve yalnızca TLS_RSA_* girişini kaldırın (diğer tüm devre dışı bırakılmış algoritmaları olduğu gibi bırakın, böylece kalan korumalar etkin kalır).
  3. apigee-service kullanarak Mesaj İşleyici'yi yeniden başlatın. Arka uç, ECDHE şifre paketlerini desteklediğinde bu geçersiz kılmayı kaldırın.
• Özel şifreleme paketi izin verilenler listesini güncelleme: conf_http_HTTPTransport.ssl.cipher.suites.whitelist politikasını daha önce geçersiz kıldıysanız yükseltme yapmadan önce inceleyin. Java 21 artık statik RSA paketlerini (TLS_RSA_*) desteklemediğinden, yalnızca bu paketleri içeren bir izin verilenler listesi, Mesaj İşlemci'yi kullanılabilir bir şifre olmadan bırakır ve arka uç çağrıları no cipher suites in common ile başarısız olur. TLS_RSA_* girişlerini kaldırın ve Java 21 uygulamanız tarafından desteklenen modern şifreleme paketlerini yapılandırın. Bu özelliği geçersiz kılmadıysanız 4.54.00 varsayılanları desteklenen paketleri zaten içerir ve herhangi bir değişiklik yapılması gerekmez.
• Dahili Yönlendirici'den Mesaj İşleyici'ye şifre paketlerini güncelleme: Daha önce conf_message-processor-communication_local.http.ssl.ciphers değerini statik RSA şifre paketleriyle geçersiz kıldıysanız yükseltme işleminden önce Java 21 uygulamanız tarafından desteklenen modern şifre paketleriyle güncelleyin. Aksi takdirde Yönlendirici, Mesaj İşleyici ile TLS el sıkışmasını tamamlayamaz. Ardından Mesaj İşleyici'yi yeniden başlatın:

  apigee-service edge-message-processor restart

  Yönlendirici ile Mesaj İşlemci arasında TLS yapılandırma başlıklı makaleyi inceleyin.

Edge bileşenleri arasında TLS yapılandırma hakkında ayrıntılı bilgi için Yönlendirici ile Mesaj İşleyici arasında TLS yapılandırma başlıklı makaleyi inceleyin.

Değişiklik algılama aracı

Apigee, Private Cloud için Edge 4.54.00 sürümüne yükseltme işleminden etkilenebilecek dağıtılmış API proxy'leri, politikalar, paylaşılan akışlar ve kaynak JAR'lar için kümenizi tarayan bir değişiklik algılama aracı sunar.

Araç; Java 21 ile uyumlu olmayan kitaplıklar, güçlü bir şekilde kapsüllenmiş dahili API'ler, eski politikaların kullanımdan kaldırılması ve OpenLDAP RDN sınırları dahil olmak üzere yükseltmeyi engelleyebilecek unsurları belirler ve uygun düzeltme stratejilerini seçmenize yardımcı olacak uygulanabilir raporlar oluşturur.

Ön koşulların tamamı, indirme talimatları, komut satırı söz dizimi ve örnek raporlar için özel Değişiklik algılama aracı kılavuzuna bakın.